diff --git a/content/build/concepts/views-for-builders/index.md b/content/build/concepts/views-for-builders/index.md index c09f66d..5048ea4 100644 --- a/content/build/concepts/views-for-builders/index.md +++ b/content/build/concepts/views-for-builders/index.md @@ -63,7 +63,7 @@ Generator clients produce six primitive collection types, all prefixed with `(EVM chains, Cosmos, …)"] + Src["Source chains
(EVM chains, Cosmos, ...)"] subgraph OffChain["Off-chain data layer"] direction TB @@ -138,12 +138,12 @@ ICA lets ShinzoHub control an account on SourceHub. When a precompile registrati flowchart TB subgraph ICA["ICA Packet"] subgraph TX["CosmosTx"] - M["MsgDirectPolicyCmd
creator: ICA account on SourceHub
policy_id: Shinzo policy ID
cmd: RegisterObjectCmd / SetRelationshipCmd / …"] + M["MsgDirectPolicyCmd
creator: ICA account on SourceHub
policy_id: Shinzo policy ID
cmd: RegisterObjectCmd / SetRelationshipCmd / ..."] end end {% end %} -The Hermes relayer (Rust binary by [Informal Systems](https://hermes.informal.systems/) is the off-chain process that physically moves packets between chains. It reads outbound packets from ShinzoHub's state, fetches Merkle proofs, and submits them to SourceHub. It then reads acknowledgements from SourceHub and returns them to ShinzoHub. Hermes is stateless and trustless. It cannot fabricate packets because SourceHub verifies each packet against a state proof. +The Hermes relayer (a Rust binary by [Informal Systems](https://hermes.informal.systems/)) is the off-chain process that physically moves packets between chains. It reads outbound packets from ShinzoHub's state, fetches Merkle proofs, and submits them to SourceHub. It then reads acknowledgements from SourceHub and returns them to ShinzoHub. Hermes is stateless and trustless. It cannot fabricate packets because SourceHub verifies each packet against a state proof. The ICA relay is asynchronous. When a precompile call triggers an ICA packet, the EVM transaction completes and returns a receipt before SourceHub has processed anything. If the ICA packet fails or times out, the EVM transaction still succeeded. The two outcomes are independent. @@ -169,7 +169,7 @@ The EVM relayer is a Go process with two pipelines: 1. The assertion pipeline subscribes to `AssertionSigned` events on the outpost's `GeneratorAssertion` contract via `eth_subscribe`, reads the assertion fields directly from the event, and broadcasts `MsgGeneratorAssertion` to ShinzoHub. No block scanning and no dependency on who built the block. 1. The payment pipeline subscribes to `PaymentCreated` log events from the outpost, extracts user `DID` and payment amount, and broadcasts `MsgRequestStreamAccess` to ShinzoHub. -The relayer maintains a persistent block cursor so it can resume where it left off after a restart. It has its own wallet on ShinzoHub and needs SHNZ for gas. +The relayer maintains a persistent block cursor so it can resume where it left off after a restart. It has its own wallet on ShinzoHub and needs SHNZ for transaction fees. {% admonition(type="note") %} The EVM relayer and the Hermes IBC relayer are completely different systems. The EVM relayer bridges EVM chains to ShinzoHub. The Hermes relayer bridges ShinzoHub to SourceHub over IBC. They share the word _relayer_ and nothing else. @@ -265,6 +265,8 @@ sequenceDiagram Host->>Host: download bundle,
load WASM lens,
start transforming {% end %} +For the developer-side view of this flow (Viewkit → ShinzoHub → Host → app SDK), see [The view lifecycle across repos](/reference/components/viewkit/#the-view-lifecycle-across-repos) in the Viewkit reference. + ## Transaction flow through a precompile The full path of an EVM transaction that hits a registry precompile and triggers a cross-chain ICA call: diff --git a/content/reference/changelog/index.md b/content/reference/changelog/index.md index 428fc18..37b2d40 100644 --- a/content/reference/changelog/index.md +++ b/content/reference/changelog/index.md @@ -12,21 +12,21 @@ Track what's new across the Shinzo developer platform: network releases, SDK cha ## Aug 06, 2026 {#08-06-2026} -### 🐳 Upgrade +### Upgrade **Generator Client** -```bash +```shell docker pull ghcr.io/shinzonetwork/shinzo-generator-client:v0.6.5.3-ethereum-mainnet ``` **Host Client** -```bash +```shell docker pull ghcr.io/shinzonetwork/shinzo-host-client:v0.6.5.3-ethereum-mainnet ``` -### 🚀 Improvements +### Improvements - {{ tag(name="Generator") }} Improved block signing performance by signing batched blocks directly from collected CIDs instead of performing a read-back query. ([PR #308](https://github.com/shinzonetwork/shinzo-generator-client/pull/308)) - {{ tag(name="Generator") }} Fixed a hardcoded Shinzo Hub URL used during testnet deployments. ([PR #313](https://github.com/shinzonetwork/shinzo-generator-client/pull/313)) @@ -37,21 +37,21 @@ docker pull ghcr.io/shinzonetwork/shinzo-host-client:v0.6.5.3-ethereum-mainnet ## July 16, 2026 {#07-16-2026} -### 🐳 Upgrade +### Upgrade **Generator Client** -```bash +```shell docker pull ghcr.io/shinzonetwork/shinzo-generator-client:v0.6.5.2-ethereum-mainnet ``` **Host Client** -```bash +```shell docker pull ghcr.io/shinzonetwork/shinzo-host-client:v0.6.5.2-ethereum-mainnet ``` -### 🚀 Improvements +### Improvements - {{ tag(name="Generator") }} Blocks are now signed only after all required block data has been received. ([PR #293](https://github.com/shinzonetwork/shinzo-generator-client/pull/293)) - {{ tag(name="Generator") }} Pruning now skips invalid or incomplete records instead of stopping the entire process. ([PR #287](https://github.com/shinzonetwork/shinzo-generator-client/pull/287)) @@ -66,21 +66,21 @@ docker pull ghcr.io/shinzonetwork/shinzo-host-client:v0.6.5.2-ethereum-mainnet ## July 08, 2026 {#07-08-2026} -### 🐳 Upgrade +### Upgrade **Generator Client** -```bash +```shell docker pull ghcr.io/shinzonetwork/shinzo-generator-client:ethereum-mainnet-latest ``` **Host Client** -```bash +```shell docker pull ghcr.io/shinzonetwork/shinzo-host-client:v0.6.5-ethereum-mainnet ``` -### 🎉 Highlights +### Highlights - Shinzō Testnet is now live. - {{ tag(name="Generator") }} Generator Client is available for Shinzo Testnet deployments. Installation instructions: [Generator Installation Guide](https://docs.shinzo.network/run/run-a-generator/install/) diff --git a/content/reference/components/generator-client/index.md b/content/reference/components/generator-client/index.md index 0faec9a..b5a9c93 100644 --- a/content/reference/components/generator-client/index.md +++ b/content/reference/components/generator-client/index.md @@ -252,7 +252,7 @@ SNAPSHOT_INTERVAL_SECONDS=60 LOG_LEVEL=error ``` -`INDEXER_START_HEIGHT` is the block number to start indexing from on first run with no existing data. Setting the value to 0 will start indexing at the tip of any chain. For a specific block select please use that blocknumber. +`INDEXER_START_HEIGHT` is the block number to start verifiable indexing from on first run with no existing data. Setting the value to 0 will start verifiable indexing at the tip of any chain. To start from a specific block, set the value to that block number. ## Chain abstraction (in progress) diff --git a/content/reference/components/host-client/index.md b/content/reference/components/host-client/index.md index e49eaaf..f978ab7 100644 --- a/content/reference/components/host-client/index.md +++ b/content/reference/components/host-client/index.md @@ -5,9 +5,9 @@ aliases = ["/reference/components"] mermaid = true +++ -The Host client receives indexed blockchain data from multiple Generator clients over P2P. It verifies the data using attestation records, runs WASM lens transforms to produce view documents, and serves those documents over GraphQL. +The Host client receives verifiable blockchain data from multiple Generator clients over P2P. It verifies the data using attestation records, runs WASM lens transforms to produce view documents, and serves those documents over GraphQL. -If Generator clients are data producers, Host clients are consumers and servers. The separation lets you scale serving independently from indexing. +If Generator clients are data producers, Host clients are consumers and servers. The separation lets you scale serving independently from verifiable indexing. ## Architecture @@ -189,7 +189,7 @@ The Host client runs LensVM (`source-gh/lens`) to execute WASM modules that tran flowchart LR In["Raw Log documents
(from generator)"] Lens["WASM Lens
filter address · ABI-decode
· map to view schema"] - Out["View documents
(USDCTransfer, …)"] + Out["View documents
(USDCTransfer, ...)"] In --> Lens --> Out {% end %} diff --git a/content/reference/components/relayer/index.md b/content/reference/components/relayer/index.md index a642290..5c4064e 100644 --- a/content/reference/components/relayer/index.md +++ b/content/reference/components/relayer/index.md @@ -54,7 +54,7 @@ The relayer maintains two connections: | Source chain | Read assertion and payment data | | ShinzoHub | Broadcast transactions | -The relayer has its own wallet on ShinzoHub and needs SHNZ for gas to broadcast transactions. It maintains a persistent block cursor so it can resume exactly where it left off after a restart. +The relayer has its own wallet on ShinzoHub and needs SHNZ for transaction fees to broadcast transactions. It maintains a persistent block cursor so it can resume exactly where it left off after a restart. ## Implementations diff --git a/content/reference/components/shinzohub/index.md b/content/reference/components/shinzohub/index.md index a64a37d..ec8b4e6 100644 --- a/content/reference/components/shinzohub/index.md +++ b/content/reference/components/shinzohub/index.md @@ -61,7 +61,7 @@ ShinzoHub uses EVM precompiled contracts to connect Cosmos module logic with the | --- | --- | --- | | `0x0210` | View Registry | Registers views | | `0x0211` | Host Registry | Tracks registered hosts | -| `0x0212` | Generator Registry | Tracks registered generator | +| `0x0212` | Generator Registry | Tracks registered generators | ### View Registry (0x0210) diff --git a/content/reference/components/viewkit/index.md b/content/reference/components/viewkit/index.md index 0d52e0e..bd78db0 100644 --- a/content/reference/components/viewkit/index.md +++ b/content/reference/components/viewkit/index.md @@ -4,40 +4,9 @@ title = "Viewkit" mermaid = true +++ -Viewkit is a CLI tool for creating, testing, and deploying views. It does not process or serve data (hosts do that). It packages a view into a binary bundle on your machine and submits a transaction to ShinzoHub. +Viewkit is the local CLI tool for creating, testing, and deploying Shinzo Views. It packages a view into a binary bundle (VWL) and submits a deploy transaction to ShinzoHub. It does not process, store, or serve data. -## What Viewkit does and does not do - -What it does: - -- Define GraphQL SDL schemas for view output. -- Configure WASM lens transforms for data mapping. -- Pre-validate transforms locally using Wasmer runtime. -- Package everything into a ViewBundle (VWL binary format). -- Deploy to ShinzoHub. - -What it does not do: - -- Process data (hosts do this). -- Store data (DefraDB does this). -- Serve queries (hosts do this). -- Run as a daemon (it is a CLI tool). - -## View definition - -A view has three pieces: - -1. A query that picks which primitive data to select (e.g., "all Logs from the USDC contract"). -1. An SDL, the GraphQL schema defining the output shape. -1. A lens (optional), a WASM module that transforms the data. - -### The @materialized directive - -In the SDL, `@materialized(if: true)` tells DefraDB to pre-compute and store the view data. `@materialized(if: false)` computes it on query. - -`@materialized(if: true)` is recommended for now. Queries are faster because data is already materialized when the query arrives. The tradeoff is more storage on the Host client. - -Important: the `limit` parameter should be on the source query (e.g., `Log(limit: 100)`), not on the materialized view collection. +This page is the technical reference for Viewkit: the full command list, filter operators, the deploy pipeline, the VWL wire format, view ID computation, and the on-disk layout of the source repo. For a hands-on walkthrough of building and deploying your first view, see the [Create a View](/build/create-a-view/) quickstart. For the conceptual overview of what Viewkit is and where it sits in the stack, see [Views for builders](/build/concepts/views-for-builders/). ## Command reference @@ -146,57 +115,9 @@ TestView_0xae1bd91e83f5a71ed4c34e18470ea3c12b9ba3d4a69cfd98717e23cf27f4eccb Because the same computation runs in both places, the client can predict the view ID before the transaction confirms. -## Lens authoring - -Lenses are WASM binaries, typically written in Rust or AssemblyScript, that transform raw primitive data into structured output. - -A simplified Rust example: - -```rust -fn transform(log: Log) -> Option { - if log.address != USDC_ADDRESS { return None; } - if log.topics[0] != TRANSFER_SIG { return None; } - Some(USDCTransfer { - from: decode_address(log.topics[1]), - to: decode_address(log.topics[2]), - amount: decode_uint256(log.data), - }) -} -``` - -Lenses must be deterministic. Any Host client running the same lens on the same data should produce identical results. - -LensVM supports bidirectional transforms (the `inverse()` function in the WASM module), though most views use one-way transforms. - -### Binary size by language - -| Language | Typical WASM size | Notes | -| --- | --- | --- | -| Rust | ~200 KB | Preferred for production | -| AssemblyScript | ~73 KB | Easier if you know TypeScript, smaller binary | - -Smaller binaries mean less P2P overhead. - -### Available lenses - -Stored in the [`wasm-bucket`](https://github.com/shinzonetwork/wasm-bucket) repository. Currently available on `main`: - -| Lens | Purpose | Arguments | -| --- | --- | --- | -| `decode_log` | ABI-decodes EVM log events into structured output | `{"abi": "[...]"}` | -| `decode_log_str` | Same as `decode_log` but `arguments` is a JSON string for `_like` filtering | `{"abi": "[...]"}` | -| `decode_function_call` | ABI-decodes function calls from transaction `input` data | `{"function_abi": "[...]", "event_abi": "[...]"}` | -| `decode_function_call_str` | Same as `decode_function_call` but `arguments` is a JSON string | `{"function_abi": "[...]", "event_abi": "[...]"}` | - -See the [Lenses guide](/reference/components/lens/) for details on each lens, output fields, and usage examples. - -### Writing new lenses - -- Rust SDK: `source-gh/lens/sdk-rust/`. -- AssemblyScript example: `source-gh/lens/tests/modules/as_wasm32_simple/`. -- WASM runtime paths: `source-gh/lens/host-go/runtimes/wasmtime/`, `wasmer/`, `wazero/`. +## Lenses -AssemblyScript lenses follow the same interface as Rust lenses. The Host client runtime does not care what language produced the WASM. +Lenses are the WASM transforms that turn raw primitive data into a View's structured output. For the available lenses, their arguments and output fields, lens argument format, determinism requirements, and how to author your own, see the [Lens reference](/reference/components/lens/). ## The view lifecycle across repos @@ -231,5 +152,3 @@ Generator clients are not involved in the View lifecycle. By the time a View is | VWL header-only decode | `shinzo-gh/viewbundle-go/header.go` | | WASM lenses | `shinzo-gh/wasm-bucket/` | | Precompile (decode/validate) | `shinzohub/app/precompiles/viewregistry/methods.go` | -| Rust lens SDK | `source-gh/lens/sdk-rust/` | -| AssemblyScript lens example | `source-gh/lens/tests/modules/as_wasm32_simple/` | diff --git a/content/reference/data-model/_index.md b/content/reference/data-model/_index.md index 2076530..1a0d9de 100644 --- a/content/reference/data-model/_index.md +++ b/content/reference/data-model/_index.md @@ -5,9 +5,9 @@ page_template = "page.html" +++ Reference for the data types, signatures, and schemas that flow through the Shinzo stack. -- [Primitives](primitives/) — the primitive collection types produced by Generator clients. -- [Signatures](signatures/) — how documents are signed and verified. -- [AttestationRecord](attestation-record/) — the attestation record type and its fields. -- [Naming convention](naming-convention/) — how collection and type names are constructed. -- [DefraDB metadata](defradb-metadata/) — metadata fields managed by DefraDB. -- [Schema directives](schema-directives/) — GraphQL SDL directives used in View schemas. +- [Primitives](primitives/): the primitive collection types produced by Generator clients. +- [Signatures](signatures/): how documents are signed and verified. +- [AttestationRecord](attestation-record/): the attestation record type and its fields. +- [Naming convention](naming-convention/): how collection and type names are constructed. +- [DefraDB metadata](defradb-metadata/): metadata fields managed by DefraDB. +- [Schema directives](schema-directives/): GraphQL SDL directives used in View schemas. diff --git a/content/reference/tools/index.md b/content/reference/tools/index.md index 76632bb..a4cd9af 100644 --- a/content/reference/tools/index.md +++ b/content/reference/tools/index.md @@ -13,7 +13,7 @@ A reference list of web interfaces and endpoints for the Shinzo network. ## RPC Endpoints -- `http://testnet.shinzo.network:8545/ ` +- `http://testnet.shinzo.network:8545/` - `wss://testnet.shinzo.network:8545/` ## Developer Tools diff --git a/content/run/run-a-host/private-hosts/index.md b/content/run/run-a-host/private-hosts/index.md index 5dcf496..38cf066 100644 --- a/content/run/run-a-host/private-hosts/index.md +++ b/content/run/run-a-host/private-hosts/index.md @@ -135,10 +135,6 @@ In a [fully air-gapped Host client](#fully-air-gapped-host-client), with `hub_ba Restart the same container, not a fresh one. `views.json` and the cached WASM lens files live in `./.defra` inside the container, and the `docker run` above doesn't mount that path. If you `docker rm` and start a new container, `views.json` is gone and the host boots with no Views. To let `views.json` survive container recreation, mount a persistent `.defra` volume as shown in [Install](/hosts/install/). -{% admonition(type="warning") %} -Running your own unpublished Views in an air-gapped host is a forthcoming capability. Viewkit can build and preview a View locally with `viewkit view deploy --target local`, but that spins up a throwaway DefraDB; it doesn't install the View into your running Host client. Deploying with `--target devnet` registers the View on ShinzoHub, which publicizes it. Until a private install path exists, an air-gapped Host client can only run Views that were already ingested from the public registry. See the [Viewkit Quickstart](/views/quickstart/) for the local build and preview flow. -{% end %} - ## What stays the same and the trade-offs - The Host client still creates `AttestationRecord`s from your Generator client's signatures and verifies them. What you lose is cross-host replication of those attestations. With no other Host peers, there's no one to gossip with. The `minimum_attestations` key is in the config but the Host client doesn't read it. It's an app-sdk setting, so changing it has no effect on a Host. diff --git a/content/understand/join-the-community/index.md b/content/understand/join-the-community/index.md index 58d987b..6a88a3e 100644 --- a/content/understand/join-the-community/index.md +++ b/content/understand/join-the-community/index.md @@ -25,7 +25,7 @@ All of Shinzo's code lives under the [shinzonetwork](https://github.com/shinzone - [shinzo-generator-client](https://github.com/shinzonetwork/shinzo-generator-client): the Generator client. - [shinzo-host-client](https://github.com/shinzonetwork/shinzo-host-client): the Host client. - [app-sdk](https://github.com/shinzonetwork/app-sdk): the Go SDK for embedding Shinzo in an application. -- [viewkit](https://github.com/shinzonetwork/viewkit): the CLI for building and deploying Views. +- [shinzo-view-creator](https://github.com/shinzonetwork/shinzo-view-creator): the CLI for building and deploying Views. To contribute code or documentation, see [Contributing](../contributing/). To report a bug, see [Get help](../get-help/).