Skip to main content

How it works

Shinzo has four kinds of moving parts:

  1. IndexersIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. that read the chain.
  2. HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. that transform and serve the data.
  3. Applications that consume that data.
  4. ShinzoHubShinzoHub Shinzo's coordination chain: a Cosmos SDK chain (v0.53.4) with an integrated EVM, running CometBFT consensus. It holds the view, host, and indexer registries and the economic layer (staking, pricing, payments). It does not store or serve indexed blockchain data., a coordination layer that tells everyone what's going on.

Data flows from left to right. Coordination happens on the side.

The data's journey​

Here's a single USDC transfer on Ethereum Mainnet, from the moment it lands on-chain to the moment an app shows it to a user.

A block arrives at a validator​

Somewhere on the network, an Ethereum validatorValidator An entity that participates in a chain's consensus. On Ethereum, a validator's withdrawal key signs an EIP-712 message on the outpost to authorize an operator key as its indexer.'s node produces or receives the block containing the transfer. The validatorValidator An entity that participates in a chain's consensus. On Ethereum, a validator's withdrawal key signs an EIP-712 message on the outpost to authorize an operator key as its indexer. is already running a full execution client (GethGeth Go-Ethereum, the Go implementation of an Ethereum node. Each indexer runs alongside a Geth node and connects over WebSocket (port 8546) and JSON-RPC (port 8545) to fetch block data., typically) and already has the data. Shinzo takes advantage of that.

The Indexer structures and signs it​

Sitting next to the Ethereum node is the Shinzo IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. (a lightweight sidecar that subscribes to new blocks over WebSocket). As each block arrives, the IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. pulls out the block metadata, transactions, logsLog A document type the indexer produces for event logs emitted during transaction execution. `topics` holds the indexed parameters and `data` holds the non-indexed ones, both as raw hex. ABI decoding happens later, in a lens., and access lists, normalizes them into structured documents, and cryptographically signs each one with its identity key. The USDC transfer shows up as a Log document with the transfer event topic, the sender, receiver, and amount, plus references back to the transaction and block it came from.

Those documents land in the IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication.'s embedded DefraDB instance. DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. handles storage, versioning, and the peer-to-peer gossip that happens next.

Hosts pick it up over P2P​

HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. subscribe to the primitive collection topics they care about (blocks, transactions, logsLog A document type the indexer produces for event logs emitted during transaction execution. `topics` holds the indexed parameters and `data` holds the non-indexed ones, both as raw hex. ABI decoding happens later, in a lens., access lists). When the IndexerIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication.'s DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. gossips the new logLog A document type the indexer produces for event logs emitted during transaction execution. `topics` holds the indexed parameters and `data` holds the non-indexed ones, both as raw hex. ABI decoding happens later, in a lens. document, subscribed HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. receive it, verify the signature, and update an attestation record for it (essentially just a running tally of how many distinct IndexersIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. have signed off on this exact piece of data). If three IndexersIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. all wrote the same logLog A document type the indexer produces for event logs emitted during transaction execution. `topics` holds the indexed parameters and `data` holds the non-indexed ones, both as raw hex. ABI decoding happens later, in a lens., the attestation record has three votes. Apps can later use those votes to set their own trust thresholds.

A View transforms primitives into something useful​

A HostHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. with thousands of raw logLog A document type the indexer produces for event logs emitted during transaction execution. `topics` holds the indexed parameters and `data` holds the non-indexed ones, both as raw hex. ABI decoding happens later, in a lens. documents isn't doing much for an app developer. That's what ViewsView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. are for. A developer writes a ViewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. that says, in effect: "take LogLog A document type the indexer produces for event logs emitted during transaction execution. `topics` holds the indexed parameters and `data` holds the non-indexed ones, both as raw hex. ABI decoding happens later, in a lens. documents, filter to the USDC contract address, decode the transfer topic using the ERC-20 ABIABI Describes how to encode and decode function calls, arguments, and event data for an EVM contract. Lenses such as `decode_log` take ABI JSON as input to read raw log data., and expose the result as a TokenTransfer type with from, to, and amount fields."

The filtering and decoding are implemented as LensLens A WASM module that transforms primitive documents (e.g., raw `Log` records) into view documents (e.g., `USDCTransfer`). Lenses must be deterministic: the same input always produces the same output. Hosts run them via LensVM. transforms, which are WASMWASM A portable, sandboxed bytecode format. Lens transforms compile to WASM — typically from Rust or AssemblyScript — and hosts run them via LensVM. modulesModule A Cosmos SDK building block that owns a slice of chain state, handles messages, and emits events. ShinzoHub adds five custom modules (`x/admin`, `x/sourcehub`, `x/host`, `x/indexer`, `x/view`) on top of the standard Cosmos set. the developer authors with viewkit and deploys to ShinzoHubShinzoHub Shinzo's coordination chain: a Cosmos SDK chain (v0.53.4) with an integrated EVM, running CometBFT consensus. It holds the view, host, and indexer registries and the economic layer (staking, pricing, payments). It does not store or serve indexed blockchain data.. HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. that choose to serve the ViewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. run those transforms against primitives as they arrive and produce viewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. documents. Because LensLens A WASM module that transforms primitive documents (e.g., raw `Log` records) into view documents (e.g., `USDCTransfer`). Lenses must be deterministic: the same input always produces the same output. Hosts run them via LensVM. transforms are deterministic, any HostHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. (or auditor) running the same transform on the same input gets the same output.

The app queries locally​

On the app side, things look (surprisingly) normal. The app embeds DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. using the app-sdk, subscribes to the TokenTransfer ViewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape., and from then on, HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. push new viewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. documents to it over P2P. The app queries them with GraphQL against its local database. No per-query API call, no network round trip, and an attestation filter available for any query that needs it.

The four participants​

Indexers​

IndexersIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. are the entry point. Reserved for Ethereum validatorsValidator An entity that participates in a chain's consensus. On Ethereum, a validator's withdrawal key signs an EIP-712 message on the outpost to authorize an operator key as its indexer. at mainnet launch (and open to any node operator on devnet), they run as a sidecar to an existing execution client. Their only job is to read the chain, produce structured and signed primitives, and hand them off. The component reference has the full Indexer spec.

Hosts​

HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. are the workhorses. They receive primitives, maintain attestation records, run ViewsView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape., and serve the resulting viewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. documents to subscribers. Anyone can run a HostHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL.. See Run a Host for operational details and Host Client reference for internals.

Developers​

Developers don't run anything on the network. They write ViewsView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. with viewkit, deploy them to ShinzoHubShinzoHub Shinzo's coordination chain: a Cosmos SDK chain (v0.53.4) with an integrated EVM, running CometBFT consensus. It holds the view, host, and indexer registries and the economic layer (staking, pricing, payments). It does not store or serve indexed blockchain data., and build applications that subscribe to the resulting data.

Applications​

Applications embed DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. locally, subscribe to the ViewsView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. they need, and query the data like a regular database. Devs have the option of filtering results by attestation threshold when correctness matters more than speed.

The coordination layer​

ShinzoHubShinzoHub Shinzo's coordination chain: a Cosmos SDK chain (v0.53.4) with an integrated EVM, running CometBFT consensus. It holds the view, host, and indexer registries and the economic layer (staking, pricing, payments). It does not store or serve indexed blockchain data. is a Cosmos SDKCosmos SDK A Go framework for building app-specific blockchains. ShinzoHub (v0.53.4) and SourceHub are both Cosmos SDK chains. ShinzoHub also bundles an EVM module. chain that sits to the side of the data path. It doesn't carry bulk data itself (that all flows over the P2P network between DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. instances). What ShinzoHubShinzoHub Shinzo's coordination chain: a Cosmos SDK chain (v0.53.4) with an integrated EVM, running CometBFT consensus. It holds the view, host, and indexer registries and the economic layer (staking, pricing, payments). It does not store or serve indexed blockchain data. does is keep the registry of who's on the network and what they can do.

That means three things in practice:

  1. ViewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. registration: When a developer deploys a ViewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape., ShinzoHubShinzoHub Shinzo's coordination chain: a Cosmos SDK chain (v0.53.4) with an integrated EVM, running CometBFT consensus. It holds the view, host, and indexer registries and the economic layer (staking, pricing, payments). It does not store or serve indexed blockchain data. validates and registers it, then emits an event that HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. listen for.
  2. Participant tracking: IndexersIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. and HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. register themselves on-chain so the rest of the network can discover them.
  3. Access control: When a user pays for access to a ViewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. via the OutpostOutpost A smart contract deployed on a source chain. Validators call it to prove their identity before registering as indexers; users call it to pay for view access in the source chain's native currency. Each chain type has its own outpost implementation. contract, ShinzoHubShinzoHub Shinzo's coordination chain: a Cosmos SDK chain (v0.53.4) with an integrated EVM, running CometBFT consensus. It holds the view, host, and indexer registries and the economic layer (staking, pricing, payments). It does not store or serve indexed blockchain data. broadcasts that grant so HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. know to start replicating data to that user. Access control is actually enforced through a separate chain called SourcehubSourceHub A separate Cosmos SDK chain built by Source Network that handles authorization for Shinzo. It runs the ACP module (based on Google's Zanzibar model) and stores authorization tuples in the form `object#relation@user`. Users never call SourceHub directly — ShinzoHub sends commands to it via ICA., connected to ShinzoHubShinzoHub Shinzo's coordination chain: a Cosmos SDK chain (v0.53.4) with an integrated EVM, running CometBFT consensus. It holds the view, host, and indexer registries and the economic layer (staking, pricing, payments). It does not store or serve indexed blockchain data. via IBCIBC A protocol for passing authenticated messages between independent blockchains. It works in layers: light clients verify state proofs, connections link two chains, channels carry ordered or unordered packets, and applications (like ICA) run on top. ShinzoHub and SourceHub communicate over IBC..

Why it's built this way​

Some design choices shape the rest of the stack and are worth understanding upfront.

Indexing lives at the validator​

ValidatorsValidator An entity that participates in a chain's consensus. On Ethereum, a validator's withdrawal key signs an EIP-712 message on the outpost to authorize an operator key as its indexer. already run full nodes, already have the block dataBlock Data Raw blockchain data: blocks, transactions, and logs. The indexer fetches this from source chains such as Ethereum and structures it into defraDB documents. the moment it's produced, and already have economic skin in the game through their 32 ETH stake. Putting indexingIndexing The process of parsing blockchain data and storing it as structured, schema-compliant documents in defraDB. there, rather than in a separate centralized service, shortens the trust path from chain to data and gets you indexingIndexing The process of parsing blockchain data and storing it as structured, schema-compliant documents in defraDB. for free as a byproduct of running infrastructure people are already running.

Indexing and transformation are separate jobs​

IndexersIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. ingest, HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. transform and serve. That split means IndexersIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication. can stay small and cheap (so validatorsValidator An entity that participates in a chain's consensus. On Ethereum, a validator's withdrawal key signs an EIP-712 message on the outpost to authorize an operator key as its indexer. will actually run them), while HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. can specialize. One HostHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL. might process every DeFi ViewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. on the network, another might focus on NFTs. It also means scaling consumer demand is a matter of adding HostsHost A Shinzo node that receives indexed data from indexers over P2P, verifies it, runs lens transforms to produce view documents, and serves those documents over GraphQL., not IndexersIndexer A node that reads blockchain data from a source chain, parses it into structured documents, and writes them to defraDB. Indexers are write-only: they push data out over P2P and reject all incoming replication..

Apps query local data, not remote APIs​

Because application clients embed DefraDBdefraDB A peer-to-peer, document-oriented database embedded in every indexer and host. It handles storage, content addressing, CRDT merging, query serving, and P2P replication via libp2p. and receive pre-processed viewView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. data over P2P, a query is a local database lookup. You don't pay per read, you don't hit rate limits, and you can verify what you got against the attestation record before you trust it. The trade-off is that your app is pushed data for the ViewsView A curated, SDL-defined representation of defraDB documents. Views transform raw indexed data into a structured output shape. it subscribes to rather than pulling arbitrary slices.