Merge pull request #498 from logos-blockchain/arjentix/speed-up-ci

feat(ci): speed up ci

.deny.toml

@@ -14,6 +14,8 @@ ignore = [
   { id = "RUSTSEC-2025-0141", reason = "`bincode` is unmaintained but continuing to use it." },
   { id = "RUSTSEC-2023-0089", reason = "atomic-polyfill is pulled transitively via risc0-zkvm; waiting on upstream fix (see https://github.com/risc0/risc0/issues/3453)" },
   { id = "RUSTSEC-2026-0097", reason = "`rand` v0.8.5 is present transitively from logos crates, modification may break integration" },
+  { id = "RUSTSEC-2026-0118", reason = "`hickory-proto` v0.25.0-alpha.5 is present transitively from logos crates, modification may break integration" },
+  { id = "RUSTSEC-2026-0119", reason = "`hickory-proto` v0.25.0-alpha.5 is present transitively from logos crates, modification may break integration" },
 ]
 yanked = "deny"
 unused-ignored-advisory = "deny"

.github/workflows/bench-regression.yml

@@ -0,0 +1,44 @@
+on:
+  pull_request:
+    paths:
+      - "tools/crypto_primitives_bench/**"
+      - "key_protocol/**"
+      - "nssa/core/**"
+      - ".github/workflows/bench-regression.yml"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+name: bench-regression
+
+jobs:
+  crypto-primitives:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.head_ref }}
+          # criterion-compare-action checks out the base branch in a second
+          # working tree, so we need the full history.
+          fetch-depth: 0
+
+      - uses: ./.github/actions/install-system-deps
+
+      - uses: ./.github/actions/install-risc0
+
+      - uses: ./.github/actions/install-logos-blockchain-circuits
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install active toolchain
+        run: rustup install
+
+      - name: Run criterion-compare against base branch
+        uses: boa-dev/criterion-compare-action@v3
+        with:
+          branchName: ${{ github.base_ref }}
+          cwd: tools/crypto_primitives_bench
+          benchName: primitives
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -94,6 +94,12 @@ jobs:
       - name: Install active toolchain
         run: rustup install
 
+      - name: Restore Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: ci-rust-cache
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+
       - name: Lint workspace
         env:
           RISC0_SKIP_BUILD: "1"
@@ -123,6 +129,12 @@ jobs:
       - name: Install active toolchain
         run: rustup install
 
+      - name: Restore Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: ci-rust-cache
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+
       - name: Install nextest
         run: cargo install --locked cargo-nextest
 
@@ -132,9 +144,74 @@ jobs:
           RUST_LOG: "info"
         run: cargo nextest run --workspace --exclude integration_tests --all-features
 
+  integration-tests-prebuild:
+    runs-on: ubuntu-latest
+    outputs:
+      targets: ${{ steps.discover-targets.outputs.targets }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.head_ref }}
+
+      - uses: ./.github/actions/install-system-deps
+
+      - uses: ./.github/actions/install-risc0
+
+      - uses: ./.github/actions/install-logos-blockchain-circuits
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install active toolchain
+        run: rustup install
+
+      - name: Restore Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: ci-rust-cache
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+
+      - name: Install nextest
+        run: cargo install --locked cargo-nextest
+
+      - name: Build integration test archive
+        env:
+          RISC0_DEV_MODE: "1"
+        run: cargo nextest archive -p integration_tests --archive-file integration-tests.tar.zst --no-pager
+
+      - name: Upload integration test archive
+        uses: actions/upload-artifact@v4
+        with:
+          name: integration-tests-archive
+          path: integration-tests.tar.zst
+
+      - name: Discover integration test targets from archive
+        id: discover-targets
+        run: |
+          cargo nextest list \
+            --archive-file integration-tests.tar.zst \
+            --list-type binaries-only \
+            --message-format json \
+            --no-pager > integration-tests-binaries.json
+
+          targets_json="$(jq -c '[."rust-binaries" | to_entries[] | select(.value.kind == "test" and .value."binary-name" != "tps") | .value."binary-name"] | sort | unique' integration-tests-binaries.json)"
+
+          if [[ "$targets_json" == "[]" ]]; then
+            echo "No integration test targets were discovered." >&2
+            exit 1
+          fi
+
+          echo "targets=$targets_json" >> "$GITHUB_OUTPUT"
+          echo "Discovered integration targets: $targets_json"
+
   integration-tests:
+    needs: integration-tests-prebuild
     runs-on: ubuntu-latest
-    timeout-minutes: 60
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        target: ${{ fromJson(needs.integration-tests-prebuild.outputs.targets) }}
+    name: integration-tests (${{ matrix.target }})
     steps:
       - uses: actions/checkout@v5
         with:
@@ -151,33 +228,10 @@ jobs:
       - name: Install active toolchain
         run: rustup install
 
-      - name: Install nextest
+      - name: Download integration test archive
-        run: cargo install --locked cargo-nextest
+        uses: actions/download-artifact@v4
-
-      - name: Run tests
-        env:
-          RISC0_DEV_MODE: "1"
-          RUST_LOG: "info"
-        run: cargo nextest run -p integration_tests -- --skip tps_test --skip indexer
-
-  integration-tests-indexer:
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    steps:
-      - uses: actions/checkout@v5
         with:
-          ref: ${{ github.event.pull_request.head.sha || github.head_ref }}
+          name: integration-tests-archive
-
-      - uses: ./.github/actions/install-system-deps
-
-      - uses: ./.github/actions/install-risc0
-
-      - uses: ./.github/actions/install-logos-blockchain-circuits
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install active toolchain
-        run: rustup install
 
       - name: Install nextest
         run: cargo install --locked cargo-nextest
@@ -186,11 +240,11 @@ jobs:
         env:
           RISC0_DEV_MODE: "1"
           RUST_LOG: "info"
-        run: cargo nextest run -p integration_tests indexer -- --skip tps_test
+        run: cargo nextest run --archive-file integration-tests.tar.zst -E "binary(${{ matrix.target }})"
 
   valid-proof-test:
     runs-on: ubuntu-latest
-    timeout-minutes: 60
+    timeout-minutes: 90
     steps:
       - uses: actions/checkout@v5
         with:
@@ -207,6 +261,12 @@ jobs:
       - name: Install active toolchain
         run: rustup install
 
+      - name: Restore Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: ci-rust-cache
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+
       - name: Test valid proof
         env:
           RUST_LOG: "info"
@@ -224,8 +284,14 @@ jobs:
 
       - uses: ./.github/actions/install-risc0
 
+      - name: Restore Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: ci-rust-cache
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+
       - name: Install just
-        run: cargo install just
+        run: cargo install --locked just
 
       - name: Build artifacts
         run: just build-artifacts

CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+We're glad you're interested in contributing to Logos Execution Zone!
+
+This document describes the guidelines for contributing to the project. We will be updating it as we grow and we figure out what works best for us.
+
+If you have any questions, come say hi to our [Discord](https://discord.gg/tGJwgGrSPN)!
+
+## Commit title format
+
+We use [Conventional Commits](https://www.conventionalcommits.org/).
+
+Use:
+- `type(scope): description`
+- `type(scope)!: description` for breaking changes
+
+Allowed `type` values:
+- `feat`
+- `fix`
+- `chore`
+- `docs`
+- `test`
+- `refactor`
+- `perf`
+- `build`
+- `ci`
+- `revert`
+
+Examples:
+- `feat(nssa): add private PDA support`
+- `fix(wallet): correct fee calculation`
+- `feat(nssa)!: rename AccountId::from((prog, seed)) to AccountId::for_public_pda`
+
+Breaking changes:
+- Mark with `!` in the title.
+
+`CHANGELOG.md` is generated from these markers on every `v*` tag via `git-cliff`, and GitHub Releases are created from the same content.
+
+## Pull requests
+
+PR titles should follow the same Conventional Commits format:
+- `type(scope): description`
+- `type(scope)!: description` for breaking changes
+
+Before marking a PR as ready for review:
+- Fill out the PR template.
+
+Breaking changes in PRs:
+- Optionally add a `BREAKING CHANGE:` footer in the PR body with migration notes.
+
+Before merging a PR, consider squashing non-meaningful commits. E.g.:
+
+```
+- refactor(wallet): move user keys to a separate module
+- revert(wallet): revert "refactor(wallet): move user keys to a separate module"
+```
+
+Could be squashed to an empty commit if they belong to the same PR.
+
+## Branch workflow
+
+When bringing your feature branch up to date, prefer rebasing on top of `main`.
+
+- Preferred: `git rebase main`
+- Avoid: `git merge main` in feature branches
+
+This keeps commit history cleaner and makes reviews easier.
+
+## Useful commands
+
+We have [`Justfile`](./Justfile) which contains some useful utilities which may help you.
+
+To list all of them run the command: `just`.
+
+Any change to our core crates may invalidate our RISC0 [`artifacts`](./artifacts/), in that case you're required to run `just build-artifacts` to update them.
+
+## AI-assisted contributions
+
+AI tools are allowed for drafting code, docs, tests, and review suggestions.
+
+Requirements:
+- A human author is fully responsible for all submitted code and text.
+- The person opening the PR must review, verify, and be able to explain every change.
+- Do not open PRs automatically via AI agents or bots. Automatic AI-created PRs are not allowed.

Cargo.toml

@@ -20,6 +20,9 @@ members = [
   "programs/token",
   "programs/associated_token_account/core",
   "programs/associated_token_account",
+  "programs/authenticated_transfer/core",
+  "programs/faucet/core",
+  "programs/vault/core",
   "sequencer/core",
   "sequencer/service",
   "sequencer/service/protocol",
@@ -36,9 +39,13 @@ members = [
   "examples/program_deployment",
   "examples/program_deployment/methods",
   "examples/program_deployment/methods/guest",
-  "bedrock_client",
   "testnet_initial_state",
-  "indexer_ffi",
+  "indexer/ffi",
+  "keycard_wallet",
+  "test_fixtures",
+  "tools/cycle_bench",
+  "tools/crypto_primitives_bench",
+  "tools/integration_bench",
 ]
 
 [workspace.dependencies]
@@ -58,7 +65,7 @@ indexer_service_protocol = { path = "indexer/service/protocol" }
 indexer_service_rpc = { path = "indexer/service/rpc" }
 wallet = { path = "wallet" }
 wallet-ffi = { path = "wallet-ffi", default-features = false }
-indexer_ffi = { path = "indexer_ffi" }
+indexer_ffi = { path = "indexer/ffi" }
 clock_core = { path = "programs/clock/core" }
 token_core = { path = "programs/token/core" }
 token_program = { path = "programs/token" }
@@ -66,9 +73,13 @@ amm_core = { path = "programs/amm/core" }
 amm_program = { path = "programs/amm" }
 ata_core = { path = "programs/associated_token_account/core" }
 ata_program = { path = "programs/associated_token_account" }
+authenticated_transfer_core = { path = "programs/authenticated_transfer/core" }
+faucet_core = { path = "programs/faucet/core" }
+vault_core = { path = "programs/vault/core" }
 test_program_methods = { path = "test_program_methods" }
-bedrock_client = { path = "bedrock_client" }
 testnet_initial_state = { path = "testnet_initial_state" }
+keycard_wallet = { path = "keycard_wallet" }
+test_fixtures = { path = "test_fixtures" }
 
 tokio = { version = "1.50", features = [
   "net",
@@ -77,9 +88,10 @@ tokio = { version = "1.50", features = [
   "fs",
 ] }
 tokio-util = "0.7.18"
-risc0-zkvm = { version = "3.0.5", features = ['std'] }
+risc0-zkvm = { version = "3.0.5", default-features = false, features = ['std'] }
 risc0-build = "3.0.5"
 anyhow = "1.0.98"
+derive_more = "2.1.1"
 num_cpus = "1.13.1"
 openssl = { version = "0.10", features = ["vendored"] }
 openssl-probe = { version = "0.1.2" }
@@ -121,12 +133,14 @@ url = { version = "2.5.4", features = ["serde"] }
 tokio-retry = "0.3.0"
 schemars = "1.2"
 async-stream = "0.3.6"
+criterion = { version = "0.8", features = ["html_reports"] }
 
-logos-blockchain-common-http-client = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "1da154c74b911318fb853d37261f8a05ffe513b4" }
+logos-blockchain-common-http-client = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "ee281a447d95a951752461ee0a6e88eb4a0f17cf" }
-logos-blockchain-key-management-system-service = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "1da154c74b911318fb853d37261f8a05ffe513b4" }
+logos-blockchain-key-management-system-service = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "ee281a447d95a951752461ee0a6e88eb4a0f17cf" }
-logos-blockchain-core = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "1da154c74b911318fb853d37261f8a05ffe513b4" }
+logos-blockchain-core = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "ee281a447d95a951752461ee0a6e88eb4a0f17cf" }
-logos-blockchain-chain-broadcast-service = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "1da154c74b911318fb853d37261f8a05ffe513b4" }
+logos-blockchain-chain-broadcast-service = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "ee281a447d95a951752461ee0a6e88eb4a0f17cf" }
-logos-blockchain-chain-service = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "1da154c74b911318fb853d37261f8a05ffe513b4" }
+logos-blockchain-chain-service = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "ee281a447d95a951752461ee0a6e88eb4a0f17cf" }
+logos-blockchain-zone-sdk = { git = "https://github.com/logos-blockchain/logos-blockchain.git", rev = "ee281a447d95a951752461ee0a6e88eb4a0f17cf" }
 
 rocksdb = { version = "0.24.0", default-features = false, features = [
   "snappy",
@@ -146,6 +160,7 @@ actix-web = { version = "4.13.0", default-features = false, features = [
 ] }
 clap = { version = "4.5.42", features = ["derive", "env"] }
 reqwest = { version = "0.12", features = ["json", "rustls-tls", "stream"] }
+pyo3 = { version = "0.24", features = ["auto-initialize"] }
 
 # Profile for leptos WASM release builds
 [profile.wasm-release]

Justfile

@@ -23,6 +23,12 @@ test:
     @echo "🧪 Running tests"
     RISC0_DEV_MODE=1 cargo nextest run --no-fail-fast
 
+# Run criterion benches: fast crypto primitives, then the slow PPE verify (real proving setup).
+bench:
+    @echo "📊 Running criterion benches"
+    cargo bench -p crypto_primitives_bench --bench primitives
+    cargo bench -p cycle_bench --features ppe --bench verify
+
 # Run Bedrock node in docker
 [working-directory: 'bedrock']
 run-bedrock:

bedrock/deployment-settings.yaml

@@ -39,42 +39,42 @@ cryptarchia:
       threshold: 1
       timestamp: 0
   gossipsub_protocol: /integration/logos-blockchain/cryptarchia/proto/1.0.0
-  genesis_state:
+  genesis_block:
-    mantle_tx:
+    header:
-      ops:
+      version: Bedrock
+      parent_block: '0000000000000000000000000000000000000000000000000000000000000000'
+      slot: 0
+      block_root: b5f8787ac23674822414c70eea15d842da38f2e806ede1a73cf7b5cf0277da07
+      proof_of_leadership:
+        proof: '0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'
+        entropy_contribution: '0000000000000000000000000000000000000000000000000000000000000000'
+        leader_key: '0000000000000000000000000000000000000000000000000000000000000000'
+        voucher_cm: '0000000000000000000000000000000000000000000000000000000000000000'
+    signature: '00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'
+    transactions:
+    - mantle_tx:
+        ops:
         - opcode: 0
           payload:
-            inputs: [ ]
+            inputs: []
             outputs:
-              - value: 1
+            - value: 1
-                pk: d204000000000000000000000000000000000000000000000000000000000000
+              pk: d204000000000000000000000000000000000000000000000000000000000000
-              - value: 100
+            - value: 100
-                pk: 2e03b2eff5a45478e7e79668d2a146cf2c5c7925bce927f2b1c67f2ab4fc0d26
+              pk: '2e03b2eff5a45478e7e79668d2a146cf2c5c7925bce927f2b1c67f2ab4fc0d26'
+            - value: 1
+              pk: ed266e6e887b9b97059dc1aa1b7b2e19b934291753c6336a163fe4ebaa28e717
         - opcode: 17
           payload:
-            channel_id: "0000000000000000000000000000000000000000000000000000000000000000"
+            channel_id: '0000000000000000000000000000000000000000000000000000000000000000'
-            inscription: [ 103, 101, 110, 101, 115, 105, 115 ]  # "genesis" in bytes
+            inscription: '67656e65736973'
-            parent: "0000000000000000000000000000000000000000000000000000000000000000"
+            parent: '0000000000000000000000000000000000000000000000000000000000000000'
-            signer: "0000000000000000000000000000000000000000000000000000000000000000"
+            signer: '0000000000000000000000000000000000000000000000000000000000000000'
-      execution_gas_price: 0
+        execution_gas_price: 0
-      storage_gas_price: 0
+        storage_gas_price: 0
-    ops_proofs:
+      ops_proofs:
-      - !ZkSig
+      - !Ed25519Sig '00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'
-        pi_a: [
+      - !Ed25519Sig '00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'
-          0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-          0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
-        ]
-        pi_b: [
-          0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-          0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-          0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-          0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
-        ]
-        pi_c: [
-          0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
-          0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
-        ]
-      - NoProof
 time:
   slot_duration: '1.0'
   chain_start_time: PLACEHOLDER_CHAIN_START_TIME

bedrock/docker-compose.yml

@@ -1,7 +1,7 @@
 services:
 
   logos-blockchain-node-0:
-    image: ghcr.io/logos-blockchain/logos-blockchain@sha256:c5243681b353278cabb562a176f0a5cfbefc2056f18cebc47fe0e3720c29fb12
+    image: ghcr.io/logos-blockchain/logos-blockchain@sha256:9f1829dea335c56f6ff68ae37ea872ed5313b96b69e8ffe143c02b7217de85fc
     ports:
       - "${PORT:-8080}:18080/tcp"
     volumes:

bedrock_client/Cargo.toml

@@ -1,23 +0,0 @@
-[package]
-name = "bedrock_client"
-version = "0.1.0"
-edition = "2024"
-license = { workspace = true }
-
-[lints]
-workspace = true
-
-[dependencies]
-common.workspace = true
-
-reqwest.workspace = true
-anyhow.workspace = true
-tokio-retry.workspace = true
-futures.workspace = true
-log.workspace = true
-serde.workspace = true
-humantime-serde.workspace = true
-logos-blockchain-common-http-client.workspace = true
-logos-blockchain-core.workspace = true
-logos-blockchain-chain-broadcast-service.workspace = true
-logos-blockchain-chain-service.workspace = true

bedrock_client/src/lib.rs

@@ -1,121 +0,0 @@
-use std::time::Duration;
-
-use anyhow::{Context as _, Result};
-use common::config::BasicAuth;
-use futures::{Stream, TryFutureExt as _};
-#[expect(clippy::single_component_path_imports, reason = "Satisfy machete")]
-use humantime_serde;
-use log::{info, warn};
-pub use logos_blockchain_chain_broadcast_service::BlockInfo;
-use logos_blockchain_chain_service::CryptarchiaInfo;
-pub use logos_blockchain_common_http_client::{CommonHttpClient, Error};
-pub use logos_blockchain_core::{block::Block, header::HeaderId, mantle::SignedMantleTx};
-use reqwest::{Client, Url};
-use serde::{Deserialize, Serialize};
-use tokio_retry::Retry;
-
-/// Fibonacci backoff retry strategy configuration.
-#[derive(Debug, Copy, Clone, Serialize, Deserialize)]
-pub struct BackoffConfig {
-    #[serde(with = "humantime_serde")]
-    pub start_delay: Duration,
-    pub max_retries: usize,
-}
-
-impl Default for BackoffConfig {
-    fn default() -> Self {
-        Self {
-            start_delay: Duration::from_millis(100),
-            max_retries: 5,
-        }
-    }
-}
-
-/// Simple wrapper
-/// maybe extend in the future for our purposes
-/// `Clone` is cheap because `CommonHttpClient` is internally reference counted (`Arc`).
-#[derive(Clone)]
-pub struct BedrockClient {
-    http_client: CommonHttpClient,
-    node_url: Url,
-    backoff: BackoffConfig,
-}
-
-impl BedrockClient {
-    pub fn new(backoff: BackoffConfig, node_url: Url, auth: Option<BasicAuth>) -> Result<Self> {
-        info!("Creating Bedrock client with node URL {node_url}");
-        let client = Client::builder()
-                //Add more fields if needed
-                .timeout(std::time::Duration::from_mins(1))
-                .build()
-                .context("Failed to build HTTP client")?;
-
-        let auth = auth.map(|a| {
-            logos_blockchain_common_http_client::BasicAuthCredentials::new(a.username, a.password)
-        });
-
-        let http_client = CommonHttpClient::new_with_client(client, auth);
-        Ok(Self {
-            http_client,
-            node_url,
-            backoff,
-        })
-    }
-
-    pub async fn post_transaction(&self, tx: SignedMantleTx) -> Result<Result<(), Error>, Error> {
-        Retry::spawn(self.backoff_strategy(), || async {
-            match self
-                .http_client
-                .post_transaction(self.node_url.clone(), tx.clone())
-                .await
-            {
-                Ok(()) => Ok(Ok(())),
-                Err(err) => match err {
-                    // Retry arm.
-                    // Retrying only reqwest errors: mainly connected to http.
-                    Error::Request(_) => Err(err),
-                    // Returning non-retryable error
-                    Error::Server(_) | Error::Client(_) | Error::Url(_) => Ok(Err(err)),
-                },
-            }
-        })
-        .await
-    }
-
-    pub async fn get_lib_stream(&self) -> Result<impl Stream<Item = BlockInfo>, Error> {
-        self.http_client.get_lib_stream(self.node_url.clone()).await
-    }
-
-    pub async fn get_block_by_id(
-        &self,
-        header_id: HeaderId,
-    ) -> Result<Option<Block<SignedMantleTx>>, Error> {
-        Retry::spawn(self.backoff_strategy(), || {
-            self.http_client
-                .get_block_by_id(self.node_url.clone(), header_id)
-                .inspect_err(|err| warn!("Block fetching failed with error: {err:#}"))
-        })
-        .await
-    }
-
-    pub async fn get_consensus_info(&self) -> Result<CryptarchiaInfo, Error> {
-        Retry::spawn(self.backoff_strategy(), || {
-            self.http_client
-                .consensus_info(self.node_url.clone())
-                .inspect_err(|err| warn!("Block fetching failed with error: {err:#}"))
-        })
-        .await
-    }
-
-    fn backoff_strategy(&self) -> impl Iterator<Item = Duration> {
-        let start_delay_millis = self
-            .backoff
-            .start_delay
-            .as_millis()
-            .try_into()
-            .expect("Start delay must be less than u64::MAX milliseconds");
-
-        tokio_retry::strategy::FibonacciBackoff::from_millis(start_delay_millis)
-            .take(self.backoff.max_retries)
-    }
-}

common/Cargo.toml

@@ -10,6 +10,7 @@ workspace = true
 [dependencies]
 nssa.workspace = true
 nssa_core.workspace = true
+authenticated_transfer_core.workspace = true
 clock_core.workspace = true
 
 anyhow.workspace = true

common/src/block.rs

@@ -85,9 +85,20 @@ impl HashableBlockData {
         signing_key: &nssa::PrivateKey,
         bedrock_parent_id: MantleMsgId,
     ) -> Block {
+        const PREFIX: &[u8; 32] = b"/LEE/v0.3/Message/Block/\x00\x00\x00\x00\x00\x00\x00\x00";
+
         let data_bytes = borsh::to_vec(&self).unwrap();
-        let signature = nssa::Signature::new(signing_key, &data_bytes);
+        let mut bytes = Vec::with_capacity(
-        let hash = OwnHasher::hash(&data_bytes);
+            PREFIX
+                .len()
+                .checked_add(data_bytes.len())
+                .expect("length overflow"),
+        );
+        bytes.extend_from_slice(PREFIX);
+        bytes.extend_from_slice(&data_bytes);
+
+        let hash = OwnHasher::hash(&bytes);
+        let signature = nssa::Signature::new(signing_key, &hash.0);
         Block {
             header: BlockHeader {
                 block_id: self.block_id,
@@ -103,11 +114,6 @@ impl HashableBlockData {
             bedrock_parent_id,
         }
     }
-
-    #[must_use]
-    pub fn block_hash(&self) -> BlockHash {
-        OwnHasher::hash(&borsh::to_vec(&self).unwrap())
-    }
 }
 
 impl From<Block> for HashableBlockData {

common/src/test_utils.rs

@@ -47,12 +47,11 @@ pub fn produce_dummy_empty_transaction() -> NSSATransaction {
     let program_id = nssa::program::Program::authenticated_transfer_program().id();
     let account_ids = vec![];
     let nonces = vec![];
-    let instruction_data: u128 = 0;
     let message = nssa::public_transaction::Message::try_new(
         program_id,
         account_ids,
         nonces,
-        instruction_data,
+        authenticated_transfer_core::Instruction::Initialize,
     )
     .unwrap();
     let private_key = nssa::PrivateKey::try_new([1; 32]).unwrap();
@@ -78,7 +77,9 @@ pub fn create_transaction_native_token_transfer(
         program_id,
         account_ids,
         nonces,
-        balance_to_move,
+        authenticated_transfer_core::Instruction::Transfer {
+            amount: balance_to_move,
+        },
     )
     .unwrap();
     let witness_set = nssa::public_transaction::WitnessSet::for_message(&message, &[signing_key]);

common/src/transaction.rs

@@ -67,7 +67,11 @@ impl NSSATransaction {
     }
 
     /// Validates the transaction against the current state and returns the resulting diff
-    /// without applying it. Rejects transactions that modify clock system accounts.
+    /// without applying it. Rejects transactions that modify clock or faucet system accounts,
+    /// whether directly or indirectly via chain calls.
+    ///
+    /// This check is required for all user transactions. Only sequencer transactions may bypass
+    /// this check.
     pub fn validate_on_state(
         &self,
         state: &V03State,
@@ -98,6 +102,16 @@ impl NSSATransaction {
             ));
         }
 
+        let faucet_id = nssa::system_faucet_account_id();
+        if public_diff
+            .get(&faucet_id)
+            .is_some_and(|post| *post != state.get_account_by_id(faucet_id))
+        {
+            return Err(nssa::error::NssaError::InvalidInput(
+                "Transaction modifies system faucet account".into(),
+            ));
+        }
+
         Ok(diff)
     }
 

completions/README.md

@@ -93,6 +93,12 @@ Only `Public/2gJJjtG9UivBGEhA1Jz6waZQx1cwfYupC5yvKEweHaeH` is used for completio
    exec zsh
    ```
 
+> **Note:** After updating the completion script, re-run step 1 to copy the new file, then rebuild the cache:
+> ```sh
+> cp _wallet ~/.oh-my-zsh/custom/plugins/wallet/
+> rm -rf ~/.zcompdump* && exec zsh
+> ```
+
 ### Requirements
 
 The completion script calls `wallet account list` to dynamically fetch account IDs. Ensure the `wallet` command is in your `$PATH`.
@@ -197,8 +203,7 @@ wallet account get --account-id <TAB>
 2. Rebuild the completion cache:
 
    ```sh
-   rm -f ~/.zcompdump*
+   rm -rf ~/.zcompdump* && exec zsh
-   exec zsh
    ```
 
 ### Account IDs not completing

completions/bash/wallet

@@ -46,7 +46,7 @@ _wallet() {
         cword=$COMP_CWORD
     }
 
-    local commands="auth-transfer chain-info account pinata token amm check-health config restore-keys deploy-program help"
+    local commands="auth-transfer chain-info account pinata token amm ata check-health config restore-keys deploy-program help"
 
     # Find the main command and subcommand by scanning words before the cursor.
     # Global options that take a value are skipped along with their argument.
@@ -127,10 +127,10 @@ _wallet() {
                         --to-label)
                             _wallet_complete_account_label "$cur"
                             ;;
-                        --to-npk | --to-vpk | --amount)
+                        --to-npk | --to-vpk | --to-identifier | --amount)
                             ;; # no specific completion
                         *)
-                            COMPREPLY=($(compgen -W "--from --from-label --to --to-label --to-npk --to-vpk --amount" -- "$cur"))
+                            COMPREPLY=($(compgen -W "--from --from-label --to --to-label --to-npk --to-vpk --to-identifier --amount" -- "$cur"))
                             ;;
                     esac
                     ;;
@@ -187,11 +187,11 @@ _wallet() {
                 sync-private)
                     ;; # no options
                 new)
-                    # `account new` is itself a subcommand: public | private
+                    # `account new` is itself a subcommand: public | private-accounts-key
                     local new_subcmd=""
                     for ((i = subcmd_idx + 1; i < cword; i++)); do
                         case "${words[$i]}" in
-                            public | private)
+                            public | private-accounts-key)
                                 new_subcmd="${words[$i]}"
                                 break
                                 ;;
@@ -199,13 +199,26 @@ _wallet() {
                     done
 
                     if [[ -z "$new_subcmd" ]]; then
-                        COMPREPLY=($(compgen -W "public private" -- "$cur"))
+                        COMPREPLY=($(compgen -W "public private-accounts-key" -- "$cur"))
                     else
-                        case "$prev" in
+                        case "$new_subcmd" in
-                            --cci | -l | --label)
+                            public)
-                                ;; # no specific completion
+                                case "$prev" in
-                            *)
+                                    --cci | -l | --label)
-                                COMPREPLY=($(compgen -W "--cci -l --label" -- "$cur"))
+                                        ;; # no specific completion
+                                    *)
+                                        COMPREPLY=($(compgen -W "--cci -l --label" -- "$cur"))
+                                        ;;
+                                esac
+                                ;;
+                            private-accounts-key)
+                                case "$prev" in
+                                    --cci)
+                                        ;; # no specific completion
+                                    *)
+                                        COMPREPLY=($(compgen -W "--cci" -- "$cur"))
+                                        ;;
+                                esac
                                 ;;
                         esac
                     fi
@@ -289,10 +302,10 @@ _wallet() {
                         --to-label)
                             _wallet_complete_account_label "$cur"
                             ;;
-                        --to-npk | --to-vpk | --amount)
+                        --to-npk | --to-vpk | --to-identifier | --amount)
                             ;; # no specific completion
                         *)
-                            COMPREPLY=($(compgen -W "--from --from-label --to --to-label --to-npk --to-vpk --amount" -- "$cur"))
+                            COMPREPLY=($(compgen -W "--from --from-label --to --to-label --to-npk --to-vpk --to-identifier --amount" -- "$cur"))
                             ;;
                     esac
                     ;;
@@ -331,10 +344,10 @@ _wallet() {
                         --holder-label)
                             _wallet_complete_account_label "$cur"
                             ;;
-                        --holder-npk | --holder-vpk | --amount)
+                        --holder-npk | --holder-vpk | --holder-identifier | --amount)
                             ;; # no specific completion
                         *)
-                            COMPREPLY=($(compgen -W "--definition --definition-label --holder --holder-label --holder-npk --holder-vpk --amount" -- "$cur"))
+                            COMPREPLY=($(compgen -W "--definition --definition-label --holder --holder-label --holder-npk --holder-vpk --holder-identifier --amount" -- "$cur"))
                             ;;
                     esac
                     ;;
@@ -344,7 +357,7 @@ _wallet() {
         amm)
             case "$subcmd" in
                 "")
-                    COMPREPLY=($(compgen -W "new swap add-liquidity remove-liquidity help" -- "$cur"))
+                    COMPREPLY=($(compgen -W "new swap-exact-input swap-exact-output add-liquidity remove-liquidity help" -- "$cur"))
                     ;;
                 new)
                     case "$prev" in
@@ -373,7 +386,7 @@ _wallet() {
                             ;;
                     esac
                     ;;
-                swap)
+                swap-exact-input)
                     case "$prev" in
                         --user-holding-a)
                             _wallet_complete_account_id "$cur"
@@ -394,6 +407,15 @@ _wallet() {
                             ;;
                     esac
                     ;;
+                swap-exact-output)
+                    case "$prev" in
+                        --user-holding-a | --user-holding-b | --exact-amount-out | --max-amount-in | --token-definition)
+                            ;; # no specific completion
+                        *)
+                            COMPREPLY=($(compgen -W "--user-holding-a --user-holding-b --exact-amount-out --max-amount-in --token-definition" -- "$cur"))
+                            ;;
+                    esac
+                    ;;
                 add-liquidity)
                     case "$prev" in
                         --user-holding-a)
@@ -451,6 +473,68 @@ _wallet() {
             esac
             ;;
 
+        ata)
+            case "$subcmd" in
+                "")
+                    COMPREPLY=($(compgen -W "address create send burn list help" -- "$cur"))
+                    ;;
+                address)
+                    case "$prev" in
+                        --owner | --token-definition)
+                            ;; # no specific completion
+                        *)
+                            COMPREPLY=($(compgen -W "--owner --token-definition" -- "$cur"))
+                            ;;
+                    esac
+                    ;;
+                create)
+                    case "$prev" in
+                        --owner)
+                            _wallet_complete_account_id "$cur"
+                            ;;
+                        --token-definition)
+                            ;; # no specific completion
+                        *)
+                            COMPREPLY=($(compgen -W "--owner --token-definition" -- "$cur"))
+                            ;;
+                    esac
+                    ;;
+                send)
+                    case "$prev" in
+                        --from)
+                            _wallet_complete_account_id "$cur"
+                            ;;
+                        --to | --token-definition | --amount)
+                            ;; # no specific completion
+                        *)
+                            COMPREPLY=($(compgen -W "--from --token-definition --to --amount" -- "$cur"))
+                            ;;
+                    esac
+                    ;;
+                burn)
+                    case "$prev" in
+                        --holder)
+                            _wallet_complete_account_id "$cur"
+                            ;;
+                        --token-definition | --amount)
+                            ;; # no specific completion
+                        *)
+                            COMPREPLY=($(compgen -W "--holder --token-definition --amount" -- "$cur"))
+                            ;;
+                    esac
+                    ;;
+                list)
+                    case "$prev" in
+                        --owner | --token-definition)
+                            ;; # no specific completion
+                        *)
+                            COMPREPLY=($(compgen -W "--owner --token-definition" -- "$cur"))
+                            ;;
+                    esac
+                    ;;
+            esac
+            ;;
+
         config)
             case "$subcmd" in
                 "")

completions/zsh/_wallet

@@ -24,6 +24,7 @@ _wallet() {
                 'pinata:Pinata program interaction subcommand'
                 'token:Token program interaction subcommand'
                 'amm:AMM program interaction subcommand'
+                'ata:Associated Token Account program interaction subcommand'
                 'check-health:Check the wallet can connect to the node and builtin local programs match the remote versions'
                 'config:Command to setup config, get and set config fields'
                 'restore-keys:Restoring keys from given password at given depth'
@@ -52,6 +53,9 @@ _wallet() {
                 amm)
                     _wallet_amm
                     ;;
+                ata)
+                    _wallet_ata
+                    ;;
                 config)
                     _wallet_config
                     ;;
@@ -72,7 +76,7 @@ _wallet() {
 # auth-transfer subcommand
 _wallet_auth_transfer() {
     local -a subcommands
-    
+
     _arguments -C \
         '1: :->subcommand' \
         '*:: :->args'
@@ -91,16 +95,17 @@ _wallet_auth_transfer() {
                 init)
                     _arguments \
                         '--account-id[Account ID to initialize]:account_id:_wallet_account_ids' \
-                        '--account-label[Account label (alternative to --account-id)]:label:_wallet_account_labels'
+                        '--account-label[Account label (alternative to --account-id)]:label:'
                     ;;
                 send)
                     _arguments \
                         '--from[Source account ID]:from_account:_wallet_account_ids' \
-                        '--from-label[Source account label (alternative to --from)]:label:_wallet_account_labels' \
+                        '--from-label[From account label (alternative to --from)]:label:' \
                         '--to[Destination account ID (for owned accounts)]:to_account:_wallet_account_ids' \
-                        '--to-label[Destination account label (alternative to --to)]:label:_wallet_account_labels' \
+                        '--to-label[To account label (alternative to --to)]:label:' \
                         '--to-npk[Destination nullifier public key (for foreign private accounts)]:npk:' \
                         '--to-vpk[Destination viewing public key (for foreign private accounts)]:vpk:' \
+                        '--to-identifier[Identifier for the recipient private account]:identifier:' \
                         '--amount[Amount of native tokens to send]:amount:'
                     ;;
             esac
@@ -111,7 +116,7 @@ _wallet_auth_transfer() {
 # chain-info subcommand
 _wallet_chain_info() {
     local -a subcommands
-    
+
     _arguments -C \
         '1: :->subcommand' \
         '*:: :->args'
@@ -144,7 +149,7 @@ _wallet_chain_info() {
 # account subcommand
 _wallet_account() {
     local -a subcommands
-    
+
     _arguments -C \
         '1: :->subcommand' \
         '*:: :->args'
@@ -169,7 +174,7 @@ _wallet_account() {
                         '(-r --raw)'{-r,--raw}'[Get raw account data]' \
                         '(-k --keys)'{-k,--keys}'[Display keys (pk for public accounts, npk/vpk for private accounts)]' \
                         '(-a --account-id)'{-a,--account-id}'[Account ID to query]:account_id:_wallet_account_ids' \
-                        '--account-label[Account label (alternative to --account-id)]:label:_wallet_account_labels'
+                        '--account-label[Account label (alternative to --account-id)]:label:'
                     ;;
                 list|ls)
                     _arguments \
@@ -181,19 +186,27 @@ _wallet_account() {
                         '*:: :->new_args'
                     case $state in
                         account_type)
-                            compadd public private
+                            compadd public private-accounts-key
                             ;;
                         new_args)
-                            _arguments \
+                            case $line[1] in
-                                '--cci[Chain index of a parent node]:chain_index:' \
+                                public)
-                                '(-l --label)'{-l,--label}'[Label to assign to the new account]:label:'
+                                    _arguments \
+                                        '--cci[Chain index of a parent node]:chain_index:' \
+                                        '(-l --label)'{-l,--label}'[Label to assign to the new account]:label:'
+                                    ;;
+                                private-accounts-key)
+                                    _arguments \
+                                        '--cci[Chain index of a parent node]:chain_index:'
+                                    ;;
+                            esac
                             ;;
                     esac
                     ;;
                 label)
                     _arguments \
                         '(-a --account-id)'{-a,--account-id}'[Account ID to label]:account_id:_wallet_account_ids' \
-                        '--account-label[Account label (alternative to --account-id)]:label:_wallet_account_labels' \
+                        '--account-label[Account label (alternative to --account-id)]:label:' \
                         '(-l --label)'{-l,--label}'[The label to assign to the account]:label:'
                     ;;
             esac
@@ -204,7 +217,7 @@ _wallet_account() {
 # pinata subcommand
 _wallet_pinata() {
     local -a subcommands
-    
+
     _arguments -C \
         '1: :->subcommand' \
         '*:: :->args'
@@ -222,7 +235,7 @@ _wallet_pinata() {
                 claim)
                     _arguments \
                         '--to[Destination account ID to receive claimed tokens]:to_account:_wallet_account_ids' \
-                        '--to-label[Destination account label (alternative to --to)]:label:_wallet_account_labels'
+                        '--to-label[To account label (alternative to --to)]:label:'
                     ;;
             esac
             ;;
@@ -255,36 +268,38 @@ _wallet_token() {
                         '--name[Token name]:name:' \
                         '--total-supply[Total supply of tokens to mint]:total_supply:' \
                         '--definition-account-id[Account ID for token definition]:definition_account:_wallet_account_ids' \
-                        '--definition-account-label[Definition account label (alternative to --definition-account-id)]:label:_wallet_account_labels' \
+                        '--definition-account-label[Definition account label (alternative to --definition-account-id)]:label:' \
                         '--supply-account-id[Account ID to receive initial supply]:supply_account:_wallet_account_ids' \
-                        '--supply-account-label[Supply account label (alternative to --supply-account-id)]:label:_wallet_account_labels'
+                        '--supply-account-label[Supply account label (alternative to --supply-account-id)]:label:'
                     ;;
                 send)
                     _arguments \
                         '--from[Source holding account ID]:from_account:_wallet_account_ids' \
-                        '--from-label[Source account label (alternative to --from)]:label:_wallet_account_labels' \
+                        '--from-label[From account label (alternative to --from)]:label:' \
                         '--to[Destination holding account ID (for owned accounts)]:to_account:_wallet_account_ids' \
-                        '--to-label[Destination account label (alternative to --to)]:label:_wallet_account_labels' \
+                        '--to-label[To account label (alternative to --to)]:label:' \
                         '--to-npk[Destination nullifier public key (for foreign private accounts)]:npk:' \
                         '--to-vpk[Destination viewing public key (for foreign private accounts)]:vpk:' \
+                        '--to-identifier[Identifier for the recipient private account]:identifier:' \
                         '--amount[Amount of tokens to send]:amount:'
                     ;;
                 burn)
                     _arguments \
                         '--definition[Definition account ID]:definition_account:_wallet_account_ids' \
-                        '--definition-label[Definition account label (alternative to --definition)]:label:_wallet_account_labels' \
+                        '--definition-label[Definition account label (alternative to --definition)]:label:' \
                         '--holder[Holder account ID]:holder_account:_wallet_account_ids' \
-                        '--holder-label[Holder account label (alternative to --holder)]:label:_wallet_account_labels' \
+                        '--holder-label[Holder account label (alternative to --holder)]:label:' \
                         '--amount[Amount of tokens to burn]:amount:'
                     ;;
                 mint)
                     _arguments \
                         '--definition[Definition account ID]:definition_account:_wallet_account_ids' \
-                        '--definition-label[Definition account label (alternative to --definition)]:label:_wallet_account_labels' \
+                        '--definition-label[Definition account label (alternative to --definition)]:label:' \
                         '--holder[Holder account ID (for owned accounts)]:holder_account:_wallet_account_ids' \
-                        '--holder-label[Holder account label (alternative to --holder)]:label:_wallet_account_labels' \
+                        '--holder-label[Holder account label (alternative to --holder)]:label:' \
                         '--holder-npk[Holder nullifier public key (for foreign private accounts)]:npk:' \
                         '--holder-vpk[Holder viewing public key (for foreign private accounts)]:vpk:' \
+                        '--holder-identifier[Identifier for the holder private account]:identifier:' \
                         '--amount[Amount of tokens to mint]:amount:'
                     ;;
             esac
@@ -295,7 +310,7 @@ _wallet_token() {
 # amm subcommand
 _wallet_amm() {
     local -a subcommands
-    
+
     _arguments -C \
         '1: :->subcommand' \
         '*:: :->args'
@@ -304,7 +319,8 @@ _wallet_amm() {
         subcommand)
             subcommands=(
                 'new:Create a new liquidity pool'
-                'swap:Swap tokens using the AMM'
+                'swap-exact-input:Swap specifying exact input amount'
+                'swap-exact-output:Swap specifying exact output amount'
                 'add-liquidity:Add liquidity to an existing pool'
                 'remove-liquidity:Remove liquidity from a pool'
                 'help:Print this message or the help of the given subcommand(s)'
@@ -316,32 +332,40 @@ _wallet_amm() {
                 new)
                     _arguments \
                         '--user-holding-a[User token A holding account ID]:holding_a:_wallet_account_ids' \
-                        '--user-holding-a-label[User holding A account label (alternative to --user-holding-a)]:label:_wallet_account_labels' \
+                        '--user-holding-a-label[User holding A label (alternative to --user-holding-a)]:label:' \
                         '--user-holding-b[User token B holding account ID]:holding_b:_wallet_account_ids' \
-                        '--user-holding-b-label[User holding B account label (alternative to --user-holding-b)]:label:_wallet_account_labels' \
+                        '--user-holding-b-label[User holding B label (alternative to --user-holding-b)]:label:' \
                         '--user-holding-lp[User LP token holding account ID]:holding_lp:_wallet_account_ids' \
-                        '--user-holding-lp-label[User holding LP account label (alternative to --user-holding-lp)]:label:_wallet_account_labels' \
+                        '--user-holding-lp-label[User holding LP label (alternative to --user-holding-lp)]:label:' \
                         '--balance-a[Amount of token A to deposit]:balance_a:' \
                         '--balance-b[Amount of token B to deposit]:balance_b:'
                     ;;
-                swap)
+                swap-exact-input)
                     _arguments \
                         '--user-holding-a[User token A holding account ID]:holding_a:_wallet_account_ids' \
-                        '--user-holding-a-label[User holding A account label (alternative to --user-holding-a)]:label:_wallet_account_labels' \
+                        '--user-holding-a-label[User holding A label (alternative to --user-holding-a)]:label:' \
                         '--user-holding-b[User token B holding account ID]:holding_b:_wallet_account_ids' \
-                        '--user-holding-b-label[User holding B account label (alternative to --user-holding-b)]:label:_wallet_account_labels' \
+                        '--user-holding-b-label[User holding B label (alternative to --user-holding-b)]:label:' \
                         '--amount-in[Amount of tokens to swap]:amount_in:' \
                         '--min-amount-out[Minimum tokens expected in return]:min_amount_out:' \
                         '--token-definition[Definition ID of the token being provided]:token_def:'
                     ;;
+                swap-exact-output)
+                    _arguments \
+                        '--user-holding-a[User token A holding account ID]:holding_a:' \
+                        '--user-holding-b[User token B holding account ID]:holding_b:' \
+                        '--exact-amount-out[Exact amount of tokens expected out]:exact_amount_out:' \
+                        '--max-amount-in[Maximum tokens to spend]:max_amount_in:' \
+                        '--token-definition[Definition ID of the token being provided]:token_def:'
+                    ;;
                 add-liquidity)
                     _arguments \
                         '--user-holding-a[User token A holding account ID]:holding_a:_wallet_account_ids' \
-                        '--user-holding-a-label[User holding A account label (alternative to --user-holding-a)]:label:_wallet_account_labels' \
+                        '--user-holding-a-label[User holding A label (alternative to --user-holding-a)]:label:' \
                         '--user-holding-b[User token B holding account ID]:holding_b:_wallet_account_ids' \
-                        '--user-holding-b-label[User holding B account label (alternative to --user-holding-b)]:label:_wallet_account_labels' \
+                        '--user-holding-b-label[User holding B label (alternative to --user-holding-b)]:label:' \
                         '--user-holding-lp[User LP token holding account ID]:holding_lp:_wallet_account_ids' \
-                        '--user-holding-lp-label[User holding LP account label (alternative to --user-holding-lp)]:label:_wallet_account_labels' \
+                        '--user-holding-lp-label[User holding LP label (alternative to --user-holding-lp)]:label:' \
                         '--max-amount-a[Maximum amount of token A to deposit]:max_amount_a:' \
                         '--max-amount-b[Maximum amount of token B to deposit]:max_amount_b:' \
                         '--min-amount-lp[Minimum LP tokens to receive]:min_amount_lp:'
@@ -349,11 +373,11 @@ _wallet_amm() {
                 remove-liquidity)
                     _arguments \
                         '--user-holding-a[User token A holding account ID]:holding_a:_wallet_account_ids' \
-                        '--user-holding-a-label[User holding A account label (alternative to --user-holding-a)]:label:_wallet_account_labels' \
+                        '--user-holding-a-label[User holding A label (alternative to --user-holding-a)]:label:' \
                         '--user-holding-b[User token B holding account ID]:holding_b:_wallet_account_ids' \
-                        '--user-holding-b-label[User holding B account label (alternative to --user-holding-b)]:label:_wallet_account_labels' \
+                        '--user-holding-b-label[User holding B label (alternative to --user-holding-b)]:label:' \
                         '--user-holding-lp[User LP token holding account ID]:holding_lp:_wallet_account_ids' \
-                        '--user-holding-lp-label[User holding LP account label (alternative to --user-holding-lp)]:label:_wallet_account_labels' \
+                        '--user-holding-lp-label[User holding LP label (alternative to --user-holding-lp)]:label:' \
                         '--balance-lp[Amount of LP tokens to burn]:balance_lp:' \
                         '--min-amount-a[Minimum token A to receive]:min_amount_a:' \
                         '--min-amount-b[Minimum token B to receive]:min_amount_b:'
@@ -363,6 +387,61 @@ _wallet_amm() {
     esac
 }
 
+# ata subcommand
+_wallet_ata() {
+    local -a subcommands
+
+    _arguments -C \
+        '1: :->subcommand' \
+        '*:: :->args'
+
+    case $state in
+        subcommand)
+            subcommands=(
+                'address:Derive and print the Associated Token Account address (local only)'
+                'create:Create (or idempotently no-op) the Associated Token Account'
+                'send:Send tokens from owner ATA to a recipient token holding account'
+                'burn:Burn tokens from holder ATA'
+                'list:List all ATAs for a given owner across multiple token definitions'
+                'help:Print this message or the help of the given subcommand(s)'
+            )
+            _describe -t subcommands 'ata subcommands' subcommands
+            ;;
+        args)
+            case $line[1] in
+                address)
+                    _arguments \
+                        '--owner[Owner account (no privacy prefix)]:owner:' \
+                        '--token-definition[Token definition account (no privacy prefix)]:token_def:'
+                    ;;
+                create)
+                    _arguments \
+                        '--owner[Owner account with privacy prefix]:owner:_wallet_account_ids' \
+                        '--token-definition[Token definition account (no privacy prefix)]:token_def:'
+                    ;;
+                send)
+                    _arguments \
+                        '--from[Sender account with privacy prefix]:from:_wallet_account_ids' \
+                        '--token-definition[Token definition account (no privacy prefix)]:token_def:' \
+                        '--to[Recipient account (no privacy prefix)]:to:' \
+                        '--amount[Amount of tokens to send]:amount:'
+                    ;;
+                burn)
+                    _arguments \
+                        '--holder[Holder account with privacy prefix]:holder:_wallet_account_ids' \
+                        '--token-definition[Token definition account (no privacy prefix)]:token_def:' \
+                        '--amount[Amount of tokens to burn]:amount:'
+                    ;;
+                list)
+                    _arguments \
+                        '--owner[Owner account (no privacy prefix)]:owner:' \
+                        '--token-definition[Token definition accounts (no privacy prefix)]:token_def:'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
 # config subcommand
 _wallet_config() {
     local -a subcommands
@@ -435,6 +514,7 @@ _wallet_help() {
         'pinata:Pinata program interaction subcommand'
         'token:Token program interaction subcommand'
         'amm:AMM program interaction subcommand'
+        'ata:Associated Token Account program interaction subcommand'
         'check-health:Check the wallet can connect to the node'
         'config:Command to setup config, get and set config fields'
         'restore-keys:Restoring keys from given password at given depth'
@@ -468,25 +548,4 @@ _wallet_account_ids() {
     _multi_parts / accounts
 }
 
-# Helper function to complete account labels
-# Uses `wallet account list` to get available labels
-_wallet_account_labels() {
-    local -a labels
-    local line
-
-    if command -v wallet &>/dev/null; then
-        while IFS= read -r line; do
-            local label
-            # Extract label from [...] at end of line
-            label="${line##*\[}"
-            label="${label%\]}"
-            [[ -n "$label" && "$label" != "$line" ]] && labels+=("$label")
-        done < <(wallet account list 2>/dev/null)
-    fi
-
-    if (( ${#labels} > 0 )); then
-        compadd -a labels
-    fi
-}
-
 _wallet "$@"

configs/docker-all-in-one/indexer_config.json

@@ -1,160 +1,8 @@
 {
     "home": "./indexer/service",
     "consensus_info_polling_interval": "1s",
-    "bedrock_client_config": {
+    "bedrock_config": {
-        "addr": "http://logos-blockchain-node-0:18080",
+        "addr": "http://logos-blockchain-node-0:18080"
-        "backoff": {
-            "start_delay": "100ms",
-            "max_retries": 5
-        }
     },
-    "channel_id": "0101010101010101010101010101010101010101010101010101010101010101",
+    "channel_id": "0101010101010101010101010101010101010101010101010101010101010101"
-    "initial_accounts": [
-        {
-            "account_id": "6iArKUXxhUJqS7kCaPNhwMWt3ro71PDyBj7jwAyE2VQV",
-            "balance": 10000
-        },
-        {
-            "account_id": "7wHg9sbJwc6h3NP1S9bekfAzB8CHifEcxKswCKUt3YQo",
-            "balance": 20000
-        }
-    ],
-    "initial_commitments": [
-        {
-            "npk":[
-                177,
-                64,
-                1,
-                11,
-                87,
-                38,
-                254,
-                159,
-                231,
-                165,
-                1,
-                94,
-                64,
-                137,
-                243,
-                76,
-                249,
-                101,
-                251,
-                129,
-                33,
-                101,
-                189,
-                30,
-                42,
-                11,
-                191,
-                34,
-                103,
-                186,
-                227,
-                230
-            ] ,
-            "account": {
-                "program_owner": [
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0
-                ],
-                "balance": 10000,
-                "data": [],
-                "nonce": 0
-            }
-        },
-        {
-            "npk": [
-                32,
-                67,
-                72,
-                164,
-                106,
-                53,
-                66,
-                239,
-                141,
-                15,
-                52,
-                230,
-                136,
-                177,
-                2,
-                236,
-                207,
-                243,
-                134,
-                135,
-                210,
-                143,
-                87,
-                232,
-                215,
-                128,
-                194,
-                120,
-                113,
-                224,
-                4,
-                165
-            ],
-            "account": {
-                "program_owner": [
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0
-                ],
-                "balance": 20000,
-                "data": [],
-                "nonce": 0
-            }
-        }
-    ],
-    "signing_key": [
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37,
-        37
-    ]
 }

configs/docker-all-in-one/sequencer_config.json

@@ -1,7 +1,5 @@
 {
     "home": "/var/lib/sequencer_service",
-    "genesis_id": 1,
-    "is_genesis_random": true,
     "max_num_tx_in_block": 20,
     "max_block_size": "1 MiB",
     "mempool_max_size": 10000,
@@ -16,117 +14,29 @@
         "node_url": "http://logos-blockchain-node-0:18080"
     },
     "indexer_rpc_url": "ws://indexer_service:8779",
-    "initial_accounts": [
+    "genesis": [
         {
-            "account_id": "6iArKUXxhUJqS7kCaPNhwMWt3ro71PDyBj7jwAyE2VQV",
+            "supply_account": {
-            "balance": 10000
+                "account_id": "6iArKUXxhUJqS7kCaPNhwMWt3ro71PDyBj7jwAyE2VQV",
-        },
+                "balance": 10000
-        {
-            "account_id": "7wHg9sbJwc6h3NP1S9bekfAzB8CHifEcxKswCKUt3YQo",
-            "balance": 20000
-        }
-    ],
-    "initial_commitments": [
-        {
-            "npk":[
-                177,
-                64,
-                1,
-                11,
-                87,
-                38,
-                254,
-                159,
-                231,
-                165,
-                1,
-                94,
-                64,
-                137,
-                243,
-                76,
-                249,
-                101,
-                251,
-                129,
-                33,
-                101,
-                189,
-                30,
-                42,
-                11,
-                191,
-                34,
-                103,
-                186,
-                227,
-                230
-            ] ,
-            "account": {
-                "program_owner": [
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0
-                ],
-                "balance": 10000,
-                "data": [],
-                "nonce": 0
             }
         },
         {
-            "npk": [
+            "supply_account": {
-                32,
+                "account_id": "7wHg9sbJwc6h3NP1S9bekfAzB8CHifEcxKswCKUt3YQo",
-                67,
+                "balance": 20000
-                72,
+            }
-                164,
+        },
-                106,
+        {
-                53,
+            "supply_account": {
-                66,
+                "account_id": "61EsoYN6gvTLkveh1YSTMG3yJkncpHy5EGmxhSK4ew29",
-                239,
+                "balance": 10000
-                141,
+            }
-                15,
+        },
-                52,
+        {
-                230,
+            "supply_account": {
-                136,
+                "account_id": "3m6HQmCgmAvsxZtxAHPqqEqoBG4335fCG8TzxigyW7rE",
-                177,
+                "balance": 20000
-                2,
-                236,
-                207,
-                243,
-                134,
-                135,
-                210,
-                143,
-                87,
-                232,
-                215,
-                128,
-                194,
-                120,
-                113,
-                224,
-                4,
-                165
-            ],
-            "account": {
-                "program_owner": [
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0,
-                    0
-                ],
-                "balance": 20000,
-                "data": [],
-                "nonce": 0
             }
         }
     ],

docs/LEZ testnet v0.1 tutorials/keycard.md

@@ -0,0 +1,237 @@
+This tutorial walks you through using Keycard with Wallet CLI. Keycard is optional hardware that can offer enhance security to a LEZ wallet. A LEZ wallet that utilizes Keycard does not store any secret keys for public accounts (eventually, this will extend to private accounts). Instead, Wallet CLI retrieves the appropriate public keys and signatures from Keycard.
+
+
+## Keycard Setup
+
+### Required hardware
+- Keycard (Blank) - a Keycard, directly, from Keycard.tech cannot (currently) be updated to support LEE.
+- Smartcard reader
+- Applets (`math.cap` and `LEE_keycard.cap`). Eventually, both of these applets will be available in separate repos.
+  - `math.cap` is an applet to speed up computations on Keycard; developed by Bitgamma (Keycard-tech team).
+  - `LEE_keycard.cap` is an applet that contains LEE keycard protocol; developed by Bitgamma (Keycard-tech team)
+
+### Firmware installation
+Installation:
+
+1. Install math applet on your keycard; this process only needs to be done once. In the root of repo:
+    ```
+    sudo apt-get install -y default-jdk
+    wget https://github.com/martinpaljak/GlobalPlatformPro/releases/download/v25.10.20/gp.jar -P keycard_wallet/keycard_applets
+    cd keycard_wallet/keycard_applets
+    java -jar gp.jar --key c212e073ff8b4bbfaff4de8ab655221f --load math.cap
+    ```
+2. Install `keycard-desktop` from [github](https://github.com/choppu/keycard-desktop)
+    - Keycard Desktop is used to install the LEE key protocol to a blank keycard.
+    - Select (Re)Install Applet and upload the key binary (`keycard_wallet/keycard_applets/LEE_keycard.cap`).
+    ![keycard-desktop.png](keycard-desktop.png)
+    - **Important:** keycard can only connect with one application at a time; if Keycard-Desktop is using keycard then Wallet CLI cannot access the same keycard, and vice-versa.
+
+## Wallet with Keycard
+Keycard functionality is available to Wallet CLI by setting up the following Python virtual environment. The steps below can also be run via `keycard_wallet/wallet_with_keycard.sh`.
+
+```bash
+# Install appropriate version of `keycard-py`.
+git clone --branch lee-schnorr --single-branch https://github.com/bitgamma/keycard-py.git keycard_wallet/python/keycard-py
+
+# Set up virtual environment.
+python3 -m venv venv
+source venv/bin/activate
+pip install pyscard mnemonic ecdsa pyaes
+pip install -e keycard_wallet/python/keycard-py
+```
+
+**Important**: Keycard wallet commands only work within the virtual environment.
+```bash
+# In the root of LEE repo:
+source venv/bin/activate
+```
+
+## PIN entry
+
+Each Keycard command prompts for a PIN interactively. To avoid re-entering it across multiple commands, export it as an environment variable:
+
+```bash
+export KEYCARD_PIN=123456
+```
+
+Unset it when done:
+
+```bash
+unset KEYCARD_PIN
+```
+
+## Keycard Commands
+
+### Keycard
+
+| Command                     | Description                                                |
+|-----------------------------|------------------------------------------------------------|
+| `wallet keycard available`  | Checks whether a Keycard reader and card are accessible    |
+| `wallet keycard init`       | Initializes a blank Keycard with a PIN and a generated PUK |
+| `wallet keycard connect`    | Establishes and saves a pairing with the Keycard           |
+| `wallet keycard disconnect` | Unpairs the Keycard and clears the saved pairing           |
+| `wallet keycard load`       | Loads a mnemonic phrase onto the Keycard                   |
+
+1. Check keycard availability
+```bash
+wallet keycard available
+
+# Output:
+✅ Keycard is available.
+```
+
+2. Initialize a blank Keycard
+```bash
+wallet keycard init
+
+# Output:
+Keycard PIN:
+Keycard PUK: 847302916485
+Record this PUK and store it somewhere safe. It cannot be recovered.
+✅ Keycard initialized successfully.
+```
+
+3. Connect (pair and save pairing for subsequent commands)
+```bash
+wallet keycard connect
+
+# Output:
+Keycard PIN:
+✅ Keycard paired and ready.
+```
+
+4. Load a mnemonic phrase
+```bash
+# Supply mnemonic via environment variable to avoid interactive prompt
+export KEYCARD_MNEMONIC="fashion degree mountain wool question damp current pond grow dolphin chronic then"
+wallet keycard load
+unset KEYCARD_MNEMONIC
+
+# Output:
+Keycard PIN:
+✅ Keycard is now connected to wallet.
+✅ Mnemonic phrase loaded successfully.
+```
+
+5. Disconnect (unpair and clear saved pairing)
+```bash
+wallet keycard disconnect
+
+# Output:
+Keycard PIN:
+✅ Keycard unpaired and pairing cleared.
+```
+
+### Pinata (testnet)
+
+| Command               | Description                                                              |
+|-----------------------|--------------------------------------------------------------------------|
+| `wallet pinata claim` | Claims a testnet pinata reward to a public or private recipient account  |
+
+Note: The recipient account must be initialized with `wallet auth-transfer init` before claiming.
+
+`--to` accepts any of:
+- A BIP32 key path — uses Keycard (e.g. `m/44'/60'/0'/0/0`)
+- An account ID with privacy prefix (e.g. `Public/9bKm...`)
+- An account label (e.g. `my-account`)
+
+1. Claim to a Keycard public account
+```bash
+wallet pinata claim --to "m/44'/60'/0'/0/0"
+
+# Output:
+Keycard PIN:
+Computing solution for pinata...
+Found solution 989106 in 33.739525ms
+Transaction hash is fd320c01f5469e62d2486afa1d9d5be39afcca0cd01d1575905b7acd95cf6397
+```
+
+2. Claim to a local wallet account by label
+```bash
+wallet pinata claim --to my-account
+
+# Output:
+Transaction hash is 2c8a4f1e903d5b76e80214c5b82e1d46a105e28930ad71bcce48f2d07b49a16f
+```
+
+### Authenticated-transfer program
+
+| Command                     | Description                                                                   |
+|-----------------------------|-------------------------------------------------------------------------------|
+| `wallet auth-transfer init` | Registers an account with the auth-transfer program                           |
+| `wallet auth-transfer send` | Sends native tokens between accounts                                          |
+
+`--account-id` (for `init`) and `--from`/`--to` (for `send`) each accept any of:
+- A BIP32 key path — uses Keycard (e.g. `m/44'/60'/0'/0/0`)
+- An account ID with privacy prefix (e.g. `Public/9bKm...`)
+- An account label (e.g. `my-account`)
+
+For `send`, foreign recipient accounts (not in the local wallet and not a Keycard path) do not need to sign — pass their account ID directly via `--to`. Shielded sends to foreign private accounts use `--to-npk`/`--to-vpk`.
+
+1. Initialize a Keycard public account
+```bash
+wallet auth-transfer init --account-id "m/44'/60'/0'/0/0"
+
+# Output:
+Keycard PIN:
+Transaction hash is 49c16940493e1618c393645c1211b5c793d405838221c29ac6562a8a4b11c5a7
+```
+
+2. Send native tokens between two Keycard accounts
+```bash
+wallet auth-transfer send \
+  --from   "m/44'/60'/0'/0/0" \
+  --to     "m/44'/60'/0'/0/1" \
+  --amount 40
+
+# Output:
+Keycard PIN:
+Transaction hash is 1a9764ab20763dcc1ffb51c6e9badd5a6316a773759032ca48e0eee59caaf488
+```
+
+3. Send native tokens from a Keycard account to a foreign account
+```bash
+wallet auth-transfer send \
+  --from   "m/44'/60'/0'/0/0" \
+  --to     "Public/9bKmZ4n7PqVRxEtY3dWsQjA2cHrFT5LpDoGXM8wJuNv6" \
+  --amount 20
+
+# Output:
+Keycard PIN:
+Transaction hash is 3e7b2a91cf804d56fe19084b3c8b25d07e8f243829bc50addf6e2c78b4b09d34
+```
+
+4. Send native tokens from a Keycard account to a local wallet account by label
+```bash
+wallet auth-transfer send \
+  --from   "m/44'/60'/0'/0/0" \
+  --to     my-account \
+  --amount 20
+
+# Output:
+Keycard PIN:
+Transaction hash is 7d4c1b8e2f903a56fd19084b3c8b25d07e8f243829bc50addf6e2c78b4b09e45
+```
+
+## Testing
+
+Tests for Keycard commands are in `keycard_wallet/tests/keycard_tests.sh`. Run from the repo root with a Keycard connected:
+
+```bash
+bash keycard_wallet/tests/keycard_tests.sh
+```
+
+## SigningGroups
+
+`SigningGroups` (`wallet/src/signing.rs`) partitions a transaction's signers into two buckets — local accounts and Keycard accounts. This ensures that Python GIL is only used at most once per transaction, regardless of how many Keycard accounts are involved.
+
+Local signers are resolved and signed in pure Rust. Keycard signers store only their BIP32 key path; all of them are signed inside a single Python session (`connect` / `close_session`) when `sign_all` is called. The command calls `needs_pin` to decide whether to prompt for a PIN before signing.
+
+Foreign recipient accounts — those with no local key and no Keycard path — are silently skipped and require neither a signature nor a nonce.
+
+```
+SigningGroups {
+    local:   [(AccountId, PrivateKey)],   // signed in pure Rust
+    keycard: [(AccountId, BIP32Path)],    // signed via a single Python/Keycard session
+}
+```

docs/LEZ testnet v0.1 tutorials/token-transfer.md

@@ -5,6 +5,7 @@ This tutorial walks through native token transfers between public and private ac
 4. Private account creation.
 5. Native token transfer from a public account to a private account.
 6. Native token transfer from a public account to a private account owned by someone else.
+7. Sending to a private accounts key from multiple independent senders.
 
 ---
 
@@ -142,7 +143,7 @@ Account owned by authenticated-transfer program
 > Private accounts are structurally identical to public accounts, but their values are stored off-chain. On-chain, only a 32-byte commitment is recorded.
 > Transactions include encrypted private values so the owner can recover them, and the decryption keys are never shared.
 > Private accounts use two keypairs: nullifier keys for privacy-preserving executions and viewing keys for encrypting and decrypting values.
-> The private account ID is derived from the nullifier public key.
+> The private account ID is derived from the nullifier public key and a numeric identifier: `SHA256(prefix || npk || identifier)`. The same `npk` paired with different identifiers yields different, independent account IDs.
 > Private accounts can be initialized by anyone, but once initialized they can only be modified by the owner’s keys.
 > Updates include a new commitment and a nullifier for the old state, which prevents linkage between versions.
 
@@ -158,7 +159,9 @@ With vpk 02ddc96d0eb56e00ce14994cfdaec5ae1f76244180a919545983156e3519940a17
 ```
 
 > [!Tip]
-> Focus on the account ID for now. The `npk` and `vpk` values are stored locally and used to build privacy-preserving transactions. The private account ID is derived from `npk`.
+> Save this account ID. You will use it in later commands.
+
+### b. Check the account status
 
 Just like public accounts, new private accounts start out uninitialized:
 
@@ -218,21 +221,23 @@ Account owned by authenticated-transfer program
 ## 6. Native token transfer from a public account to a private account owned by someone else
 
 > [!Important]
-> We’ll simulate transferring to someone else by creating a new private account we own and treating it as if it belonged to another user.
+> We’ll simulate transferring to someone else by creating a new private accounts key and treating it as if it belonged to another user. When the recipient is someone else, you only have their `npk` and `vpk` — not an account ID.
 
-### a. Create a new uninitialized private account
+### a. Create a new private accounts key to simulate a foreign recipient
 
 ```bash
-wallet account new private
+wallet account new private-accounts-key
 
 # Output:
-Generated new account with account_id Private/AukXPRBmrYVqoqEW2HTs7N3hvTn3qdNFDcxDHVr5hMm5
+Generated new private accounts key at path /1
 With npk 0c95ebc4b3830f53da77bb0b80a276a776cdcf6410932acc718dcdb3f788a00e
 With vpk 039fd12a3674a880d3e917804129141e4170d419d1f9e28a3dcf979c1f2369cb72
 ```
 
 > [!Tip]
-> Ignore the private account ID here and use the `npk` and `vpk` values to send to a foreign private account.
+> Ignore the account ID here and use the `npk` and `vpk` values to send to a foreign private account.
+
+### b. Send 3 tokens using the recipient’s npk and vpk
 
 ```bash
 wallet auth-transfer send \
@@ -242,9 +247,74 @@ wallet auth-transfer send \
     --amount 3
 ```
 
+> [!Note]
+> `--to-identifier` is omitted here. When omitted, the wallet picks a random identifier, which is usually fine. Use the flag explicitly when a specific identifier is required.
+
 > [!Warning]
 > This command creates a privacy-preserving transaction, which may take a few minutes. The updated values are encrypted and included in the transaction.
 > Once accepted, the recipient must run `wallet account sync-private` to scan the chain for their encrypted updates and refresh local state.
 
 > [!Note]
 > You have seen transfers between two public accounts and from a public sender to a private recipient. Transfers from a private sender, whether to a public account or to another private account, follow the same pattern.
+
+## 7. Sending to a private accounts key from multiple independent senders
+
+> [!Important]
+> A private accounts key (`npk` + `vpk`) can be shared with multiple senders. Each sender independently chooses an identifier; the recipient's account ID is derived from `(npk, identifier)`. Two senders using different identifiers produce two separate private accounts under the same key.
+
+### a. Alice creates a private accounts key
+
+```bash
+wallet account new private-accounts-key
+
+# Output:
+Generated new private accounts key at path /2
+With npk a3f7c21b8e905d4f6a1bc783d0e2f94c1d5a6b7e8f9012345678abcdef012345
+With vpk 03b1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6071819202122232425262728292a2b2c
+```
+
+Alice shares the `npk` and `vpk` values with Bob and Charlie out of band.
+
+### b. Bob sends 10 tokens to Alice using identifier 1
+
+```bash
+wallet auth-transfer send \
+    --from Public/BobXqJprP9BmhbFVQyBcbznU8bAXcwrzwRoPTetXdQPA \
+    --to-npk a3f7c21b8e905d4f6a1bc783d0e2f94c1d5a6b7e8f9012345678abcdef012345 \
+    --to-vpk 03b1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6071819202122232425262728292a2b2c \
+    --to-identifier 1 \
+    --amount 10
+```
+
+### c. Charlie sends 5 tokens to Alice using identifier 2
+
+```bash
+wallet auth-transfer send \
+    --from Public/CharlieYrP9BmhbFVQyBcbznU8bAXcwrzwRoPTetXdQPB \
+    --to-npk a3f7c21b8e905d4f6a1bc783d0e2f94c1d5a6b7e8f9012345678abcdef012345 \
+    --to-vpk 03b1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6071819202122232425262728292a2b2c \
+    --to-identifier 2 \
+    --amount 5
+```
+
+> [!Note]
+> Bob and Charlie each chose a different identifier. They do not need to coordinate — any two distinct values work.
+
+### d. Alice syncs to discover the new accounts
+
+```bash
+wallet account sync-private
+```
+
+```bash
+wallet account list
+
+# Output (private account entries under key /2):
+/2 Private/AliceBobAcctXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+/2 Private/AliceCharlieAcctXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+Alice now has two separate private accounts, one funded by Bob and one by Charlie, both controlled by the same key at path `/2`.
+
+> [!Tip]
+> Alice can check each account balance with `wallet account get --account-id Private/...`. Neither balance is visible on-chain.

docs/benchmarks/README.md

@@ -0,0 +1,11 @@
+# Benchmarks
+
+Bench tools live under `tools/` with READMEs for how to run each one. This directory holds the result write-ups: machine, raw tables, and short findings.
+
+| Bench | Doc |
+|---|---|
+| cycle_bench | [cycle_bench.md](cycle_bench.md) |
+| crypto_primitives_bench | [crypto_primitives_bench.md](crypto_primitives_bench.md) |
+| integration_bench | [integration_bench.md](integration_bench.md) |
+
+All numbers are from a single M2 Pro dev box unless noted otherwise.

docs/benchmarks/crypto_primitives_bench.md

@@ -0,0 +1,56 @@
+# crypto_primitives_bench
+
+Cryptographic primitives used by client/wallet code. Measures the per-call cost of key derivation, sender-side DH for note encryption, and Account note symmetric encrypt/decrypt. Standalone host binary, no live stack required.
+
+## Machine
+
+| Field | Value |
+|---|---|
+| Chip | Apple M2 Pro (8P+4E) |
+| RAM | 16 GB |
+| OS | macOS 15.5 |
+| Rust | 1.94.0 |
+| Profile | release |
+
+## Results
+
+Criterion sample_size = 50, warm_up_time = 2 s, measurement_time = 10 s. Slope-regression point estimate in the middle column; 95% confidence interval bounds in the outer columns.
+
+| Operation | low | point | high | outliers (mild + severe) |
+|---|---:|---:|---:|---:|
+| keychain/new_os_random | 3.11 ms | 3.21 ms | 3.34 ms | 3 + 5 |
+| keychain/new_mnemonic | 3.05 ms | 3.11 ms | 3.23 ms | 0 + 2 |
+| shared_secret_key/sender_dh | 76.7 µs | 78.4 µs | 80.6 µs | 3 + 4 |
+| encryption/encrypt | 1.11 µs | 1.17 µs | 1.25 µs | 1 + 5 |
+| encryption/decrypt | 907 ns | 928 ns | 954 ns | 0 + 3 |
+
+Numbers from a single M2 Pro dev box. For full estimates (slope, mean, median, MAD, std-dev) and the noise model, see `target/criterion/<group>/<bench>/estimates.json` after running locally.
+
+## Findings
+
+- Keychain creation is dominated by the 2048-round HMAC-SHA512 PBKDF in the mnemonic-to-SSK path. ≈ 3 ms.
+- Per-recipient DH (secp256k1) is ≈ 80 µs. Outbound shielded transfers to N recipients cost ≈ 80·N µs of crypto on top of proving.
+- Symmetric encrypt/decrypt over a 49-byte Account note is sub-µs. Bulk encryption is not the bottleneck.
+
+## Reproduce
+
+```sh
+cargo bench -p crypto_primitives_bench --bench primitives
+```
+
+JSON estimates: `target/criterion/<group>/<bench>/estimates.json`. HTML report: `target/criterion/report/index.html`.
+
+## Baseline comparison
+
+```sh
+# On main:
+cargo bench -p crypto_primitives_bench --bench primitives -- --save-baseline main
+# On your branch:
+cargo bench -p crypto_primitives_bench --bench primitives -- --baseline main
+```
+
+Criterion reports per-bench change as a percentage with a 95% confidence interval; deltas within the CI are reported as "no significant change" rather than red.
+
+## Caveats
+
+- Single-thread, no SIMD acceleration. Bench dev box uses the pure-Rust secp256k1 backend.

docs/benchmarks/cycle_bench.md

@@ -0,0 +1,101 @@
+# cycle_bench
+
+Per-program Risc0 cycle counts, prover wall time, PPE composition cost, and verifier wall time for the built-in LEZ programs. Inputs for the fee model's `G_executor`, `G_prove`, `G_verify`, and `S_agg` parameters.
+
+## Machine
+
+| Field | Value |
+|---|---|
+| Chip | Apple M2 Pro (8P+4E) |
+| RAM | 16 GB |
+| OS | macOS 15.5 |
+| Rust | 1.94.0 |
+| Risc0 zkVM | 3.0.5 |
+| Profile | release |
+| GPU acceleration | none |
+
+## Executor cycles
+
+`SessionInfo::cycles()` per instruction. Deterministic across runs. Wall time is `best / mean ± stdev` over 5 timed iterations (1 warmup discarded).
+
+| Program | Instruction | user_cycles | segments | exec_ms (best / mean ± stdev) |
+|---|---|---:|---:|---|
+| authenticated_transfer | Initialize | 43,642 | 1 | 18.86 / 19.41 ± 0.48 |
+| authenticated_transfer | Transfer | 77,095 | 1 | 19.67 / 20.84 ± 1.16 |
+| token | Burn | 116,546 | 1 | 24.86 / 25.46 ± 0.63 |
+| token | Mint | 116,862 | 1 | 24.47 / 25.08 ± 0.42 |
+| token | Transfer | 127,726 | 1 | 25.00 / 25.40 ± 0.29 |
+| clock | Tick (no rollups) | 137,022 | 1 | 21.18 / 21.57 ± 0.41 |
+| ata | Create | 175,056 | 1 | 23.64 / 24.94 ± 1.09 |
+| amm | SwapExactInput | 508,634 | 1 | 34.21 / 34.77 ± 0.55 |
+| amm | AddLiquidity | 642,774 | 1 | 37.59 / 37.87 ± 0.28 |
+
+## Real proving (`--prove`)
+
+`prover.prove(env, elf)` wall time per program on CPU. `total_cycles` is `user_cycles` rounded up to the next power of two (Risc0 padding).
+
+| Program | Instruction | total_cycles | prove_ms | prove_s |
+|---|---|---:|---:|---:|
+| authenticated_transfer | Initialize | 131,072 | 11,881 | 11.9 |
+| authenticated_transfer | Transfer | 131,072 | 13,705 | 13.7 |
+| token | Burn | 262,144 | 22,893 | 22.9 |
+| token | Mint | 262,144 | 23,927 | 23.9 |
+| token | Transfer | 262,144 | 27,178 | 27.2 |
+| clock | Tick | 262,144 | 23,486 | 23.5 |
+| ata | Create | 262,144 | 21,093 | 21.1 |
+| amm | AddLiquidity | 1,048,576 | 111,654 | 111.7 |
+| amm | SwapExactInput | 1,048,576 | 126,400 | 126.4 |
+
+Linear fit across po2 buckets: ≈ 100 µs per total cycle (≈ 10k cycles/s throughput on this CPU).
+
+## PPE composition + chain-call sweep (`--ppe`)
+
+Same `auth_transfer Transfer` instruction, standalone vs wrapped in the privacy circuit; plus the `chain_caller` test program with N chained `authenticated_transfer` calls. `proof_bytes` is the borsh-serialized. InnerReceipt (S_agg in the fee model).
+
+| Case | prove_ms | prove_s | proof_bytes |
+|---|---:|---:|---:|
+| auth_transfer Transfer standalone | 13,705 | 13.7 | n/a |
+| auth_transfer Transfer in PPE | 61,486 | 61.5 | 223,551 |
+| chain_caller depth=1 | 122,590 | 122.6 | 223,551 |
+| chain_caller depth=3 | 231,974 | 232.0 | 223,551 |
+| chain_caller depth=5 | 372,123 | 372.1 | 223,551 |
+| chain_caller depth=9 | 544,280 | 544.3 | 223,551 |
+
+Linear fit depth=1..9: ≈ 53 s per additional chained call, intercept ≈ 73 s. Composition tax (single program PPE − standalone): ≈ 48 s. `proof_bytes` is constant: the outer succinct proof has fixed size; the journal carried alongside it scales with public state and is reported separately by `--verify`.
+
+## Verifier (criterion bench)
+
+One PPE receipt generated once (auth_transfer Transfer in PPE), then `Receipt::verify(PRIVACY_PRESERVING_CIRCUIT_ID)` measured under criterion's statistical sampler. Bench file: `tools/cycle_bench/benches/verify.rs`. Setup (one full PPE prove) is outside the timed `iter` loop.
+
+Numbers from the most recent local run on the machine listed above. Criterion sample_size = 100, measurement_time = 15 s, warm_up_time = 2 s. Slope-regression point estimate in the middle column; 95% CI bounds on either side. Run `cargo bench -p cycle_bench --features ppe --bench verify` to refresh.
+
+| Bench | low | point | high | outliers (mild + severe) |
+|---|---:|---:|---:|---:|
+| ppe/verify_auth_transfer | 12.016 ms | 12.215 ms | 12.469 ms | 1 + 10 |
+
+The corresponding `proof_bytes` (S_agg) for the bench receipt is captured by `--ppe` above; the verify bench itself only times the verify call.
+
+## Findings
+
+- Proving cost scales with po2-bucketed `total_cycles`, not raw `user_cycles`. Trimming user_cycles only helps if it crosses a 2^N boundary.
+- Single-program PPE composition tax on M2 Pro CPU: ≈ 48 s (61.5 − 13.7).
+- Chained-call cost is linear at ≈ 53 s per call. A max-depth chain (10) would take ≈ 600 s standalone on this CPU.
+- `G_verify` is ≈ 12 ms (criterion CI: 12.0–12.5 ms over 100 samples) and roughly constant per outer receipt. The succinct outer proof is fixed at 223,551 bytes (S_agg); verify is not on the latency critical path.
+
+## Reproduce
+
+```sh
+cargo run --release -p cycle_bench
+cargo run --release -p cycle_bench --features prove -- --prove
+cargo run --release -p cycle_bench --features ppe -- --prove --ppe
+
+# Verifier microbench via criterion:
+cargo bench -p cycle_bench --features ppe --bench verify
+```
+
+JSON output: `target/cycle_bench.json` (bin), `target/criterion/ppe/verify_auth_transfer/` (verify bench).
+
+## Caveats
+
+- CPU-only proving on a dev laptop. Production prover hardware (GPU, specialised CPU pipelines) will produce much smaller numbers; relative ordering should be preserved.
+- Single-segment cases only; multi-segment programs would pay continuation overhead not measured here.

docs/benchmarks/integration_bench.md

@@ -0,0 +1,120 @@
+# integration_bench
+
+End-to-end LEZ scenarios driven through the wallet against a docker-compose Bedrock node + in-process sequencer + indexer (via `test_fixtures::TestContext`). Times each step and records borsh sizes per block, split by tx variant.
+
+Numbers below are from a single-host docker-compose run on an Apple M2 Pro (CPU only, no GPU acceleration). Absolute wall time and block sizes depend heavily on the bedrock config (block cadence and confirmation depth) and on dev-mode vs real proving; re-run the bench locally to characterise your own setup.
+
+## Scenarios
+
+| Scenario | Description |
+|---|---|
+| token | Sequential public token Send + one shielded recipient setup. |
+| amm | Pool create, add liquidity, swap, remove liquidity. All public. |
+| fanout | One sender → N recipients, sequential. All public. |
+| private | Shielded, deshielded, private→private chained private flow. |
+| parallel | N senders submit concurrently into one block. All public. |
+
+## Dev-mode vs real-proving
+
+`RISC0_DEV_MODE=1` makes the prover emit stub receipts instead of running the recursive STARK pipeline. The table compares each quantity in dev mode vs real proving for the two classes of scenarios:
+
+| Quantity | Public-only scenarios (dev → real) | PPE-bearing scenarios (dev → real) |
+|---|---|---|
+| Wall time per step | same in both modes | real adds ~100 s per PPE step |
+| `public_tx_bytes` | same in both modes | same in both modes |
+| `ppe_tx_bytes` | n/a | dev ≈ 2 KB stub → real ≈ 225 KB (matches `S_agg` from cycle_bench) |
+| `block_bytes` | same in both modes | real adds ~225 KB per PPE tx in the block |
+| `bedrock_finality_s` | same in both modes | same in both modes (L1 cadence, not LEZ prover) |
+| Blocks captured | similar in both modes | real captures more empty clock-only ticks that fill prove wall-time |
+
+Tables below report dev-mode for all five scenarios. Real-proving numbers are included for `amm_swap_flow` (representative all-public) and `private_chained_flow` (representative chained-private flow); public-only scenarios converge between modes within run-to-run jitter, so a full real-proving sweep is not run here.
+
+## Methodology
+
+Per scenario, every produced block is fetched via `getBlock(BlockId)` and serialized with `borsh::to_vec(&Block)`. Each transaction is serialized individually and counted by variant. Empty clock-only ticks give the per-block fixed-cost baseline. Wall time is captured per step (submit + inclusion + wallet sync) and aggregated to the per-scenario `total_s`. The one-time stack-setup cost (`shared_setup_s` at the run level) and the closing bedrock finality wait (`bedrock_finality_s` per scenario) are reported separately, not folded into `total_s`.
+
+## Step latencies — dev mode (`RISC0_DEV_MODE=1`)
+
+Per-scenario wall time and Bedrock L1-finality latency for the closing tip.
+
+| Scenario | total_s | bedrock_finality_s |
+|---|---:|---:|
+| token_onboarding | 61.36 | 5.88 |
+| amm_swap_flow | 156.50 | 27.99 |
+| multi_recipient_fanout | 214.40 | 31.71 |
+| private_chained_flow | 109.31 | 8.73 |
+| parallel_fanout | 234.42 | 20.29 |
+
+Shared TestContext setup: 139.80 s (paid once per run). Total dev-mode wall time across all five scenarios: 1010.4 s.
+
+## Step latencies — real proving (selected scenarios)
+
+| Scenario | total_s | bedrock_finality_s | Δ vs dev |
+|---|---:|---:|---:|
+| amm_swap_flow | 156.20 | 26.95 | ~0 (all-public) |
+| private_chained_flow | 391.74 | 9.40 | +282.4 s (≈ 94 s per PPE step × 3) |
+
+Per-step breakdown for `private_chained_flow` in real proving:
+
+| Step | submit_s | inclusion_s | total_s |
+|---|---:|---:|---:|
+| token_new_fungible (public) | 0.003 | 10.857 | 11.006 |
+| shielded_transfer (PPE) | 125.416 | 0.001 | 125.469 |
+| deshielded_transfer (PPE) | 126.261 | 0.001 | 126.311 |
+| private_to_private (PPE) | 128.875 | 0.001 | 128.934 |
+
+PPE steps move the cost from `inclusion_s` (waiting for the next sealed block) to `submit_s` (the wallet itself proving the PPE circuit before sending). Each PPE prove is ≈ 127 s on this CPU.
+
+## Block + tx sizes (borsh) — dev mode
+
+Per scenario, every produced block is fetched via `getBlock(BlockId)` and serialized with `borsh::to_vec(&Block)`. Each transaction is serialized individually and counted by variant. The empty clock-only ticks at `min` give the per-block fixed-cost baseline (≈ 334 bytes across all scenarios).
+
+| Scenario | blocks | block_bytes (mean) | block_bytes (min..max) | public_tx (mean / n) | ppe_tx (mean / n) |
+|---|---:|---:|---|---:|---:|
+| token_onboarding | 6 | 881 | 334..2,890 | 206 / 8 | 2,556 / 1 |
+| amm_swap_flow | 16 | 553 | 334..1,011 | 248 / 24 | n/a |
+| multi_recipient_fanout | 22 | 513 | 334..707 | 221 / 33 | n/a |
+| private_chained_flow | 10 | 1,186 | 334..3,565 | 173 / 11 | 2,715 / 3 |
+| parallel_fanout | 24 | 646 | 334..3,904 | 248 / 45 | n/a |
+
+## Block + tx sizes (borsh) — real proving
+
+| Scenario | blocks | block_bytes (mean) | block_bytes (min..max) | public_tx (mean / n) | ppe_tx (mean / n) |
+|---|---:|---:|---|---:|---:|
+| amm_swap_flow | 16 | 553 | 334..1,011 | 248 / 24 | n/a |
+| private_chained_flow | 39 | 17,707 | 334..226,578 | 158 / 40 | 225,728 / 3 |
+
+`amm_swap_flow` is byte-identical between dev and real (no proof payload). `private_chained_flow`'s `ppe_tx_bytes` matches the cycle_bench `S_agg` measurement (≈ 225 KB borsh InnerReceipt). The `block_bytes` max (226,578) is the block containing the largest PPE transaction.
+
+## Findings
+
+- Public-only scenarios converge between dev mode and real proving in both latency and byte counts. Either mode is suitable to characterize them.
+- PPE transactions are ≈ 225 KB on the wire in real proving, dominated by the outer succinct proof. Dev mode emits a ≈ 2.7 KB stub that does not represent the L1 payload; fee-model storage gas inputs must come from a real-proving run.
+- Per-PPE-step prove cost on this CPU is ≈ 127 s, paid on the wallet side at submit time, not on the sequencer. For a single-program chained flow the cost stacks linearly.
+- Empty clock-only ticks set the per-block fixed-cost baseline at ≈ 334 bytes across all scenarios and both modes.
+- Bedrock L1 finality varies in the 6 to 32 s range across scenarios, driven by L1 cadence and which tick the closing wait happens to land on, not by the LEZ prover.
+
+## Reproduce
+
+Prerequisite: a running local Docker daemon (the `bedrock/docker-compose.yml` is brought up by the bench).
+
+```sh
+# Dev-mode sweep (fast)
+RISC0_DEV_MODE=1 cargo run --release -p integration_bench -- --scenario all
+
+# Real-proving for representative private flow
+cargo run --release -p integration_bench -- --scenario private
+
+# Real-proving for representative public flow
+cargo run --release -p integration_bench -- --scenario amm
+```
+
+JSON output: `target/integration_bench_dev.json` / `target/integration_bench_prove.json` (suffix toggled by `RISC0_DEV_MODE`).
+
+## Caveats
+
+- Dev-mode `ppe_tx_bytes` and PPE-step latencies are not representative of production; use real-proving numbers for any fee-model input that touches the storage or prover-cost components.
+- Single-host run, no GPU acceleration. Real-proving on production prover hardware will move per-step latencies by orders of magnitude; byte counts will not change.
+- Bedrock running locally via docker-compose; no real network latency between sequencer and Bedrock.
+- Bedrock L1 finality (`bedrock_finality_s`) is set by the bedrock config in `bedrock/docker-compose.yml` (block cadence × confirmation depth). Different configs will shift `bedrock_finality_s` materially.
+- All scenarios share a single TestContext for the run (one bedrock + sequencer + indexer + wallet for the whole run, chain state accumulating across scenarios), which matches how the node runs in production.

examples/program_deployment/src/bin/run_hello_world_with_authorization.rs

@@ -50,8 +50,8 @@ async fn main() {
     // Load signing keys to provide authorization
     let signing_key = wallet_core
         .storage()
-        .user_data
+        .key_chain()
-        .get_pub_account_signing_key(account_id)
+        .pub_account_signing_key(account_id)
         .expect("Input account should be a self owned public account");
 
     // Define the desired greeting in ASCII

explorer_service/src/api.rs

@@ -86,7 +86,7 @@ pub async fn get_block_by_id(block_id: BlockId) -> Result<Block, ServerFnError>
 
 /// Get latest block ID
 #[server]
-pub async fn get_latest_block_id() -> Result<BlockId, ServerFnError> {
+pub async fn get_latest_block_id() -> Result<Option<BlockId>, ServerFnError> {
     use indexer_service_rpc::RpcClient as _;
     let client = expect_context::<IndexerRpcClient>();
     client

flake.nix

@@ -2,7 +2,9 @@
   description = "Logos Execution Zone";
 
   inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    logos-liblogos.url = "github:logos-co/logos-liblogos";
+
+    nixpkgs.follows = "logos-liblogos/nixpkgs";
 
     rust-overlay = {
       url = "github:oxalica/rust-overlay";
@@ -139,7 +141,7 @@
               cargoExtraArgs = "-p indexer_ffi";
               postInstall = ''
                 mkdir -p $out/include
-                cp indexer_ffi/indexer_ffi.h $out/include/
+                cp indexer/ffi/indexer_ffi.h $out/include/
               ''
               + pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
                 install_name_tool -id @rpath/libindexer_ffi.dylib $out/lib/libindexer_ffi.dylib

indexer/core/Cargo.toml

@@ -9,7 +9,7 @@ workspace = true
 
 [dependencies]
 common.workspace = true
-bedrock_client.workspace = true
+logos-blockchain-zone-sdk.workspace = true
 nssa.workspace = true
 nssa_core.workspace = true
 storage.workspace = true
@@ -19,13 +19,14 @@ anyhow.workspace = true
 log.workspace = true
 serde.workspace = true
 humantime-serde.workspace = true
-tokio.workspace = true
 borsh.workspace = true
 futures.workspace = true
 url.workspace = true
 logos-blockchain-core.workspace = true
 serde_json.workspace = true
 async-stream.workspace = true
+tokio.workspace = true
 
 [dev-dependencies]
 tempfile.workspace = true
+authenticated_transfer_core.workspace = true

indexer/core/src/block_store.rs

@@ -1,11 +1,13 @@
 use std::{path::Path, sync::Arc};
 
-use anyhow::Result;
+use anyhow::{Context as _, Result};
-use bedrock_client::HeaderId;
 use common::{
     block::{BedrockStatus, Block},
     transaction::{NSSATransaction, clock_invocation},
 };
+use log::info;
+use logos_blockchain_core::{header::HeaderId, mantle::ops::channel::MsgId};
+use logos_blockchain_zone_sdk::Slot;
 use nssa::{Account, AccountId, V03State};
 use nssa_core::BlockId;
 use storage::indexer::RocksDBIO;
@@ -20,14 +22,10 @@ pub struct IndexerStore {
 impl IndexerStore {
     /// Starting database at the start of new chain.
     /// Creates files if necessary.
-    ///
+    pub fn open_db(location: &Path) -> Result<Self> {
-    /// ATTENTION: Will overwrite genesis block.
+        let initial_state = testnet_initial_state::initial_state();
-    pub fn open_db_with_genesis(
+        let dbio = RocksDBIO::open_or_create(location, &initial_state)?;
-        location: &Path,
+
-        genesis_block: &Block,
-        initial_state: &V03State,
-    ) -> Result<Self> {
-        let dbio = RocksDBIO::open_or_create(location, genesis_block, initial_state)?;
         let current_state = dbio.final_state()?;
 
         Ok(Self {
@@ -43,8 +41,8 @@ impl IndexerStore {
             .map(HeaderId::from))
     }
 
-    pub fn get_last_block_id(&self) -> Result<u64> {
+    pub fn get_last_block_id(&self) -> Result<Option<u64>> {
-        Ok(self.dbio.get_meta_last_block_in_db()?)
+        self.dbio.get_meta_last_block_id_in_db().map_err(Into::into)
     }
 
     pub fn get_block_at_id(&self, id: u64) -> Result<Option<Block>> {
@@ -85,24 +83,36 @@ impl IndexerStore {
         Ok(self.dbio.get_acc_transactions(acc_id, offset, limit)?)
     }
 
-    #[must_use]
+    pub fn genesis_id(&self) -> Result<Option<u64>> {
-    pub fn genesis_id(&self) -> u64 {
         self.dbio
-            .get_meta_first_block_in_db()
+            .get_meta_first_block_id_in_db()
-            .expect("Must be set at the DB startup")
+            .map_err(Into::into)
     }
 
-    #[must_use]
+    pub fn last_block(&self) -> Result<Option<u64>> {
-    pub fn last_block(&self) -> u64 {
+        self.dbio.get_meta_last_block_id_in_db().map_err(Into::into)
-        self.dbio
-            .get_meta_last_block_in_db()
-            .expect("Must be set at the DB startup")
     }
 
     pub fn get_state_at_block(&self, block_id: u64) -> Result<V03State> {
         Ok(self.dbio.calculate_state_for_id(block_id)?)
     }
 
+    pub fn get_zone_cursor(&self) -> Result<Option<(MsgId, Slot)>> {
+        let Some(bytes) = self.dbio.get_zone_sdk_indexer_cursor_bytes()? else {
+            return Ok(None);
+        };
+        let cursor: (MsgId, Slot) = serde_json::from_slice(&bytes)
+            .context("Failed to deserialize stored zone-sdk indexer cursor")?;
+        Ok(Some(cursor))
+    }
+
+    pub fn set_zone_cursor(&self, cursor: &(MsgId, Slot)) -> Result<()> {
+        let bytes =
+            serde_json::to_vec(cursor).context("Failed to serialize zone-sdk indexer cursor")?;
+        self.dbio.put_zone_sdk_indexer_cursor_bytes(&bytes)?;
+        Ok(())
+    }
+
     /// Recalculation of final state directly from DB.
     ///
     /// Used for indexer healthcheck.
@@ -118,7 +128,14 @@ impl IndexerStore {
             .get_account_by_id(*account_id))
     }
 
+    pub fn account_state_at_block(&self, account_id: &AccountId, block_id: u64) -> Result<Account> {
+        Ok(self
+            .get_state_at_block(block_id)?
+            .get_account_by_id(*account_id))
+    }
+
     pub async fn put_block(&self, mut block: Block, l1_header: HeaderId) -> Result<()> {
+        info!("Applying block {}", block.header.block_id);
         {
             let mut state_guard = self.current_state.write().await;
 
@@ -133,15 +150,33 @@ impl IndexerStore {
                 "Last transaction in block must be the clock invocation for the block timestamp"
             );
 
+            let is_genesis = block.header.block_id == 1;
             for transaction in user_txs {
-                transaction
+                if is_genesis {
-                    .clone()
+                    let genesis_tx = match transaction {
-                    .transaction_stateless_check()?
+                        NSSATransaction::Public(public_tx) => public_tx,
-                    .execute_check_on_state(
+                        NSSATransaction::PrivacyPreserving(_)
-                        &mut state_guard,
+                        | NSSATransaction::ProgramDeployment(_) => {
-                        block.header.block_id,
+                            anyhow::bail!("Genesis block should contain only public transactions")
-                        block.header.timestamp,
+                        }
-                    )?;
+                    };
+                    state_guard
+                        .transition_from_public_transaction(
+                            genesis_tx,
+                            block.header.block_id,
+                            block.header.timestamp,
+                        )
+                        .context("Failed to execute genesis public transaction")?;
+                } else {
+                    transaction
+                        .clone()
+                        .transaction_stateless_check()?
+                        .execute_check_on_state(
+                            &mut state_guard,
+                            block.header.block_id,
+                            block.header.timestamp,
+                        )?;
+                }
             }
 
             // Apply the clock invocation directly (it is expected to modify clock accounts).
@@ -160,104 +195,131 @@ impl IndexerStore {
         // to represent correct block finality
         block.bedrock_status = BedrockStatus::Finalized;
 
+        info!("Putting block {} into DB", block.header.block_id);
         Ok(self.dbio.put_block(&block, l1_header.into())?)
     }
 }
 
 #[cfg(test)]
 mod tests {
-    use nssa::{AccountId, PublicKey};
+    use common::{HashType, block::HashableBlockData};
     use tempfile::tempdir;
+    use testnet_initial_state::initial_pub_accounts_private_keys;
 
     use super::*;
 
-    fn genesis_block() -> Block {
-        common::test_utils::produce_dummy_block(1, None, vec![])
-    }
-
-    fn acc1_sign_key() -> nssa::PrivateKey {
-        nssa::PrivateKey::try_new([1; 32]).unwrap()
-    }
-
-    fn acc2_sign_key() -> nssa::PrivateKey {
-        nssa::PrivateKey::try_new([2; 32]).unwrap()
-    }
-
-    fn acc1() -> AccountId {
-        AccountId::from(&PublicKey::new_from_private_key(&acc1_sign_key()))
-    }
-
-    fn acc2() -> AccountId {
-        AccountId::from(&PublicKey::new_from_private_key(&acc2_sign_key()))
-    }
-
     #[test]
     fn correct_startup() {
         let home = tempdir().unwrap();
 
-        let storage = IndexerStore::open_db_with_genesis(
+        let storage = IndexerStore::open_db(home.as_ref()).unwrap();
-            home.as_ref(),
-            &genesis_block(),
-            &nssa::V03State::new_with_genesis_accounts(
-                &[(acc1(), 10000), (acc2(), 20000)],
-                vec![],
-                0,
-            ),
-        )
-        .unwrap();
 
-        let block = storage.get_block_at_id(1).unwrap().unwrap();
         let final_id = storage.get_last_block_id().unwrap();
 
-        assert_eq!(block.header.hash, genesis_block().header.hash);
+        assert_eq!(final_id, None);
-        assert_eq!(final_id, 1);
     }
 
     #[tokio::test]
     async fn state_transition() {
         let home = tempdir().unwrap();
 
-        let storage = IndexerStore::open_db_with_genesis(
+        let storage = IndexerStore::open_db(home.as_ref()).unwrap();
-            home.as_ref(),
-            &genesis_block(),
-            &nssa::V03State::new_with_genesis_accounts(
-                &[(acc1(), 10000), (acc2(), 20000)],
-                vec![],
-                0,
-            ),
-        )
-        .unwrap();
 
-        let mut prev_hash = genesis_block().header.hash;
+        let initial_accounts = initial_pub_accounts_private_keys();
+        let from = initial_accounts[0].account_id;
+        let to = initial_accounts[1].account_id;
+        let sign_key = initial_accounts[0].pub_sign_key.clone();
 
-        let from = acc1();
+        // Submit genesis block
-        let to = acc2();
+        let clock_tx = NSSATransaction::Public(clock_invocation(0));
-        let sign_key = acc1_sign_key();
+        let genesis_block_data = HashableBlockData {
+            block_id: 1,
+            prev_block_hash: HashType::default(),
+            timestamp: 0,
+            transactions: vec![clock_tx],
+        };
+        let genesis_block = genesis_block_data.into_pending_block(
+            &common::test_utils::sequencer_sign_key_for_testing(),
+            [0; 32],
+        );
+        let mut prev_hash = Some(genesis_block.header.hash);
+        storage
+            .put_block(genesis_block, HeaderId::from([0_u8; 32]))
+            .await
+            .unwrap();
 
-        for i in 2..10 {
+        for i in 0..10 {
             let tx = common::test_utils::create_transaction_native_token_transfer(
-                from,
+                from, i, to, 10, &sign_key,
-                i - 2,
-                to,
-                10,
-                &sign_key,
             );
-            let block_id = u64::try_from(i).unwrap();
+            let block_id = u64::try_from(i + 1).unwrap();
 
-            let next_block =
+            let next_block = common::test_utils::produce_dummy_block(block_id, prev_hash, vec![tx]);
-                common::test_utils::produce_dummy_block(block_id, Some(prev_hash), vec![tx]);
+            prev_hash = Some(next_block.header.hash);
-            prev_hash = next_block.header.hash;
 
             storage
-                .put_block(next_block, HeaderId::from([u8::try_from(i).unwrap(); 32]))
+                .put_block(
+                    next_block,
+                    HeaderId::from([u8::try_from(i + 1).unwrap(); 32]),
+                )
                 .await
                 .unwrap();
         }
 
-        let acc1_val = storage.account_current_state(&acc1()).await.unwrap();
+        let acc1_val = storage.account_current_state(&from).await.unwrap();
-        let acc2_val = storage.account_current_state(&acc2()).await.unwrap();
+        let acc2_val = storage.account_current_state(&to).await.unwrap();
 
-        assert_eq!(acc1_val.balance, 9920);
+        assert_eq!(acc1_val.balance, 9900);
-        assert_eq!(acc2_val.balance, 20080);
+        assert_eq!(acc2_val.balance, 20100);
+    }
+
+    #[tokio::test]
+    async fn account_state_at_block() {
+        let home = tempdir().unwrap();
+
+        let storage = IndexerStore::open_db(home.as_ref()).unwrap();
+
+        let mut prev_hash = None;
+
+        let initial_accounts = initial_pub_accounts_private_keys();
+        let from = initial_accounts[0].account_id;
+        let to = initial_accounts[1].account_id;
+        let sign_key = initial_accounts[0].pub_sign_key.clone();
+
+        for i in 0..10 {
+            let tx = common::test_utils::create_transaction_native_token_transfer(
+                from, i, to, 10, &sign_key,
+            );
+            let block_id = u64::try_from(i + 1).unwrap();
+
+            let next_block = common::test_utils::produce_dummy_block(block_id, prev_hash, vec![tx]);
+            prev_hash = Some(next_block.header.hash);
+
+            storage
+                .put_block(
+                    next_block,
+                    HeaderId::from([u8::try_from(i + 1).unwrap(); 32]),
+                )
+                .await
+                .unwrap();
+        }
+
+        // Genesis block: no transfers applied yet.
+        let acc1_at_1 = storage.account_state_at_block(&from, 1).unwrap();
+        let acc2_at_1 = storage.account_state_at_block(&to, 1).unwrap();
+        assert_eq!(acc1_at_1.balance, 9990);
+        assert_eq!(acc2_at_1.balance, 20010);
+
+        // After block 5: 4 transfers of 10 applied (one each in blocks 2..=5).
+        let acc1_at_5 = storage.account_state_at_block(&from, 5).unwrap();
+        let acc2_at_5 = storage.account_state_at_block(&to, 5).unwrap();
+        assert_eq!(acc1_at_5.balance, 9950);
+        assert_eq!(acc2_at_5.balance, 20050);
+
+        // After final block 9: 8 transfers applied; should match current state.
+        let acc1_at_9 = storage.account_state_at_block(&from, 9).unwrap();
+        let acc2_at_9 = storage.account_state_at_block(&to, 9).unwrap();
+        assert_eq!(acc1_at_9.balance, 9910);
+        assert_eq!(acc2_at_9.balance, 20090);
     }
 }

indexer/core/src/config.rs

@@ -6,18 +6,14 @@ use std::{
 };
 
 use anyhow::{Context as _, Result};
-pub use bedrock_client::BackoffConfig;
 use common::config::BasicAuth;
 use humantime_serde;
 pub use logos_blockchain_core::mantle::ops::channel::ChannelId;
 use serde::{Deserialize, Serialize};
-use testnet_initial_state::{PrivateAccountPublicInitialData, PublicAccountPublicInitialData};
 use url::Url;
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ClientConfig {
-    /// For individual RPC requests we use Fibonacci backoff retry strategy.
-    pub backoff: BackoffConfig,
     pub addr: Url,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub auth: Option<BasicAuth>,
@@ -25,18 +21,12 @@ pub struct ClientConfig {
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct IndexerConfig {
-    /// Home dir of sequencer storage.
+    /// Home dir of indexer storage.
     pub home: PathBuf,
-    /// Sequencers signing key.
-    pub signing_key: [u8; 32],
     #[serde(with = "humantime_serde")]
     pub consensus_info_polling_interval: Duration,
-    pub bedrock_client_config: ClientConfig,
+    pub bedrock_config: ClientConfig,
     pub channel_id: ChannelId,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub initial_public_accounts: Option<Vec<PublicAccountPublicInitialData>>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub initial_private_accounts: Option<Vec<PrivateAccountPublicInitialData>>,
 }
 
 impl IndexerConfig {

indexer/core/src/lib.rs

@@ -1,18 +1,14 @@
-use std::collections::VecDeque;
+use std::sync::Arc;
 
 use anyhow::Result;
-use bedrock_client::{BedrockClient, HeaderId};
+use common::block::Block;
-use common::{
+// ToDo: Remove after testnet
-    HashType, PINATA_BASE58,
+use futures::StreamExt as _;
-    block::{Block, HashableBlockData},
+use log::{error, info, warn};
+use logos_blockchain_core::header::HeaderId;
+use logos_blockchain_zone_sdk::{
+    CommonHttpClient, ZoneMessage, adapter::NodeHttpClient, indexer::ZoneIndexer,
 };
-use log::{debug, error, info};
-use logos_blockchain_core::mantle::{
-    Op, SignedMantleTx,
-    ops::channel::{ChannelId, inscribe::InscriptionOp},
-};
-use nssa::V03State;
-use testnet_initial_state::initial_state_testnet;
 
 use crate::{block_store::IndexerStore, config::IndexerConfig};
 
@@ -21,364 +17,97 @@ pub mod config;
 
 #[derive(Clone)]
 pub struct IndexerCore {
-    pub bedrock_client: BedrockClient,
+    pub zone_indexer: Arc<ZoneIndexer<NodeHttpClient>>,
     pub config: IndexerConfig,
     pub store: IndexerStore,
 }
 
-#[derive(Clone)]
-/// This struct represents one L1 block data fetched from backfilling.
-pub struct BackfillBlockData {
-    l2_blocks: Vec<Block>,
-    l1_header: HeaderId,
-}
-
-#[derive(Clone)]
-/// This struct represents data fetched fom backfilling in one iteration.
-pub struct BackfillData {
-    block_data: VecDeque<BackfillBlockData>,
-    curr_fin_l1_lib_header: HeaderId,
-}
-
 impl IndexerCore {
     pub fn new(config: IndexerConfig) -> Result<Self> {
-        let hashable_data = HashableBlockData {
-            block_id: 1,
-            transactions: vec![],
-            prev_block_hash: HashType([0; 32]),
-            timestamp: 0,
-        };
-
-        // Genesis creation is fine as it is,
-        // because it will be overwritten by sequencer.
-        // Therefore:
-        // ToDo: remove key from indexer config, use some default.
-        let signing_key = nssa::PrivateKey::try_new(config.signing_key).unwrap();
-        let channel_genesis_msg_id = [0; 32];
-        let genesis_block = hashable_data.into_pending_block(&signing_key, channel_genesis_msg_id);
-
-        let initial_private_accounts: Option<Vec<(nssa_core::Commitment, nssa_core::Nullifier)>> =
-            config.initial_private_accounts.as_ref().map(|accounts| {
-                accounts
-                    .iter()
-                    .map(|init_comm_data| {
-                        let npk = &init_comm_data.npk;
-
-                        let mut acc = init_comm_data.account.clone();
-
-                        acc.program_owner =
-                            nssa::program::Program::authenticated_transfer_program().id();
-
-                        (
-                            nssa_core::Commitment::new(npk, &acc),
-                            nssa_core::Nullifier::for_account_initialization(npk),
-                        )
-                    })
-                    .collect()
-            });
-
-        let init_accs: Option<Vec<(nssa::AccountId, u128)>> = config
-            .initial_public_accounts
-            .as_ref()
-            .map(|initial_accounts| {
-                initial_accounts
-                    .iter()
-                    .map(|acc_data| (acc_data.account_id, acc_data.balance))
-                    .collect()
-            });
-
-        // If initial commitments or accounts are present in config, need to construct state from
-        // them
-        let state = if initial_private_accounts.is_some() || init_accs.is_some() {
-            let mut state = V03State::new_with_genesis_accounts(
-                &init_accs.unwrap_or_default(),
-                initial_private_accounts.unwrap_or_default(),
-                genesis_block.header.timestamp,
-            );
-
-            // ToDo: Remove after testnet
-            state.add_pinata_program(PINATA_BASE58.parse().unwrap());
-
-            state
-        } else {
-            initial_state_testnet()
-        };
-
         let home = config.home.join("rocksdb");
 
+        let basic_auth = config.bedrock_config.auth.clone().map(Into::into);
+        let node = NodeHttpClient::new(
+            CommonHttpClient::new(basic_auth),
+            config.bedrock_config.addr.clone(),
+        );
+        let zone_indexer = ZoneIndexer::new(config.channel_id, node);
+
         Ok(Self {
-            bedrock_client: BedrockClient::new(
+            zone_indexer: Arc::new(zone_indexer),
-                config.bedrock_client_config.backoff,
-                config.bedrock_client_config.addr.clone(),
-                config.bedrock_client_config.auth.clone(),
-            )?,
             config,
-            store: IndexerStore::open_db_with_genesis(&home, &genesis_block, &state)?,
+            store: IndexerStore::open_db(&home)?,
         })
     }
 
-    pub fn subscribe_parse_block_stream(&self) -> impl futures::Stream<Item = Result<Block>> {
+    pub fn subscribe_parse_block_stream(&self) -> impl futures::Stream<Item = Result<Block>> + '_ {
+        let poll_interval = self.config.consensus_info_polling_interval;
+        let initial_cursor = self
+            .store
+            .get_zone_cursor()
+            .expect("Failed to load zone-sdk indexer cursor");
+
         async_stream::stream! {
-            info!("Searching for initial header");
+            let mut cursor = initial_cursor;
 
-            let last_stored_l1_lib_header = self.store.last_observed_l1_lib_header()?;
+            if cursor.is_some() {
-
+                info!("Resuming indexer from cursor {cursor:?}");
-            let mut prev_last_l1_lib_header = if let Some(last_l1_lib_header) = last_stored_l1_lib_header {
-                info!("Last l1 lib header found: {last_l1_lib_header}");
-                last_l1_lib_header
             } else {
-                info!("Last l1 lib header not found in DB");
+                info!("Starting indexer from beginning of channel");
-                info!("Searching for the start of a channel");
+            }
-
-                let BackfillData {
-                    block_data: start_buff,
-                    curr_fin_l1_lib_header: last_l1_lib_header,
-                } = self.search_for_channel_start().await?;
-
-                for BackfillBlockData {
-                    l2_blocks: l2_block_vec,
-                    l1_header,
-                } in start_buff {
-                    let mut l2_blocks_parsed_ids: Vec<_> = l2_block_vec.iter().map(|block| block.header.block_id).collect();
-                    l2_blocks_parsed_ids.sort_unstable();
-                    info!("Parsed {} L2 blocks with ids {:?}", l2_block_vec.len(), l2_blocks_parsed_ids);
-
-                    for l2_block in l2_block_vec {
-                        // TODO: proper fix is to make the sequencer's genesis include a
-                        // trailing `clock_invocation(0)` (and have the indexer's
-                        // `open_db_with_genesis` not pre-apply state transitions) so the
-                        // inscribed genesis can flow through `put_block` like any other
-                        // block. For now we skip re-applying it.
-                        //
-                        // The channel-start (block_id == 1) is the sequencer's genesis
-                        // inscription that we re-discover during initial search. The
-                        // indexer already has its own locally-constructed genesis in
-                        // the store from `open_db_with_genesis`, so re-applying the
-                        // inscribed copy is both redundant and would fail the strict
-                        // block validation in `put_block` (the inscribed genesis lacks
-                        // the trailing clock invocation).
-                        if l2_block.header.block_id != 1 {
-                            self
-                            .store
-                            .put_block(l2_block.clone(), l1_header)
-                            .await
-                            .inspect_err(|err| error!("Failed to put block with err {err:?}"))?;
-                        }
-
-                        yield Ok(l2_block);
-                    }
-                }
-
-                last_l1_lib_header
-            };
-
-            info!("Searching for initial header finished");
-
-            info!("Starting backfilling from {prev_last_l1_lib_header}");
 
             loop {
-                let BackfillData {
+                let stream = match self.zone_indexer.next_messages(cursor).await {
-                    block_data: buff,
+                    Ok(s) => s,
-                    curr_fin_l1_lib_header,
+                    Err(err) => {
-                } = self
+                        error!("Failed to start zone-sdk next_messages stream: {err}");
-                    .backfill_to_last_l1_lib_header_id(prev_last_l1_lib_header, &self.config.channel_id)
+                        tokio::time::sleep(poll_interval).await;
-                    .await
+                        continue;
-                    .inspect_err(|err| error!("Failed to backfill to last l1 lib header id with err {err:#?}"))?;
-
-                prev_last_l1_lib_header = curr_fin_l1_lib_header;
-
-                for BackfillBlockData {
-                    l2_blocks: l2_block_vec,
-                    l1_header: header,
-                } in buff {
-                    let mut l2_blocks_parsed_ids: Vec<_> = l2_block_vec.iter().map(|block| block.header.block_id).collect();
-                    l2_blocks_parsed_ids.sort_unstable();
-                    info!("Parsed {} L2 blocks with ids {:?}", l2_block_vec.len(), l2_blocks_parsed_ids);
-
-                    for l2_block in l2_block_vec {
-                        self.store.put_block(l2_block.clone(), header).await?;
-
-                        yield Ok(l2_block);
                     }
-                }
-            }
-        }
-    }
-
-    async fn get_lib(&self) -> Result<HeaderId> {
-        Ok(self.bedrock_client.get_consensus_info().await?.lib)
-    }
-
-    async fn get_next_lib(&self, prev_lib: HeaderId) -> Result<HeaderId> {
-        loop {
-            let next_lib = self.get_lib().await?;
-            if next_lib == prev_lib {
-                info!(
-                    "Wait {:?} to not spam the node",
-                    self.config.consensus_info_polling_interval
-                );
-                tokio::time::sleep(self.config.consensus_info_polling_interval).await;
-            } else {
-                break Ok(next_lib);
-            }
-        }
-    }
-
-    /// WARNING: depending on channel state,
-    /// may take indefinite amount of time.
-    pub async fn search_for_channel_start(&self) -> Result<BackfillData> {
-        let mut curr_last_l1_lib_header = self.get_lib().await?;
-        let mut backfill_start = curr_last_l1_lib_header;
-        // ToDo: How to get root?
-        let mut backfill_limit = HeaderId::from([0; 32]);
-        // ToDo: Not scalable, initial buffer should be stored in DB to not run out of memory
-        // Don't want to complicate DB even more right now.
-        let mut block_buffer = VecDeque::new();
-
-        'outer: loop {
-            let mut cycle_header = curr_last_l1_lib_header;
-
-            loop {
-                let Some(cycle_block) = self.bedrock_client.get_block_by_id(cycle_header).await?
-                else {
-                    // First run can reach root easily
-                    // so here we are optimistic about L1
-                    // failing to get parent.
-                    break;
                 };
+                let mut stream = std::pin::pin!(stream);
 
-                // It would be better to have id, but block does not have it, so slot will do.
+                while let Some((msg, slot)) = stream.next().await {
-                info!(
+                    let zone_block = match msg {
-                    "INITIAL SEARCH: Observed L1 block at slot {}",
+                        ZoneMessage::Block(b) => b,
-                    cycle_block.header().slot().into_inner()
+                        // Non-block messages don't carry a cursor position; the
-                );
+                        // next ZoneBlock advances past them implicitly.
-                debug!(
+                        ZoneMessage::Deposit(_) | ZoneMessage::Withdraw(_) => continue,
-                    "INITIAL SEARCH: This block header is {}",
+                    };
-                    cycle_block.header().id()
-                );
-                debug!(
-                    "INITIAL SEARCH: This block parent is {}",
-                    cycle_block.header().parent()
-                );
 
-                let (l2_block_vec, l1_header) =
+                    let block: Block = match borsh::from_slice(&zone_block.data) {
-                    parse_block_owned(&cycle_block, &self.config.channel_id);
+                        Ok(b) => b,
+                        Err(e) => {
+                            error!("Failed to deserialize L2 block from zone-sdk: {e}");
+                            // Advance past the broken inscription so we don't
+                            // re-process it on restart.
+                            cursor = Some((zone_block.id, slot));
+                            if let Err(err) = self.store.set_zone_cursor(&(zone_block.id, slot)) {
+                                warn!("Failed to persist indexer cursor: {err:#}");
+                            }
+                            continue;
+                        }
+                    };
 
-                info!("Parsed {} L2 blocks", l2_block_vec.len());
+                    info!("Indexed L2 block {}", block.header.block_id);
 
-                if !l2_block_vec.is_empty() {
+                    // TODO: Remove l1_header placeholder once storage layer
-                    block_buffer.push_front(BackfillBlockData {
+                    // no longer requires it. Zone-sdk handles L1 tracking internally.
-                        l2_blocks: l2_block_vec.clone(),
+                    let placeholder_l1_header = HeaderId::from([0_u8; 32]);
-                        l1_header,
+                    if let Err(err) = self.store.put_block(block.clone(), placeholder_l1_header).await {
-                    });
+                        error!("Failed to store block {}: {err:#}", block.header.block_id);
-                }
-
-                if let Some(first_l2_block) = l2_block_vec.first()
-                    && first_l2_block.header.block_id == 1
-                {
-                    info!("INITIAL_SEARCH: Found channel start");
-                    break 'outer;
-                }
-
-                // Step back to parent
-                let parent = cycle_block.header().parent();
-
-                if parent == backfill_limit {
-                    break;
-                }
-
-                cycle_header = parent;
-            }
-
-            info!("INITIAL_SEARCH: Reached backfill limit, refetching last l1 lib header");
-
-            block_buffer.clear();
-            backfill_limit = backfill_start;
-            curr_last_l1_lib_header = self.get_next_lib(curr_last_l1_lib_header).await?;
-            backfill_start = curr_last_l1_lib_header;
-        }
-
-        Ok(BackfillData {
-            block_data: block_buffer,
-            curr_fin_l1_lib_header: curr_last_l1_lib_header,
-        })
-    }
-
-    pub async fn backfill_to_last_l1_lib_header_id(
-        &self,
-        last_fin_l1_lib_header: HeaderId,
-        channel_id: &ChannelId,
-    ) -> Result<BackfillData> {
-        let curr_fin_l1_lib_header = self.get_next_lib(last_fin_l1_lib_header).await?;
-        // ToDo: Not scalable, buffer should be stored in DB to not run out of memory
-        // Don't want to complicate DB even more right now.
-        let mut block_buffer = VecDeque::new();
-
-        let mut cycle_header = curr_fin_l1_lib_header;
-        loop {
-            let Some(cycle_block) = self.bedrock_client.get_block_by_id(cycle_header).await? else {
-                return Err(anyhow::anyhow!("Parent not found"));
-            };
-
-            if cycle_block.header().id() == last_fin_l1_lib_header {
-                break;
-            }
-            // Step back to parent
-            cycle_header = cycle_block.header().parent();
-
-            // It would be better to have id, but block does not have it, so slot will do.
-            info!(
-                "Observed L1 block at slot {}",
-                cycle_block.header().slot().into_inner()
-            );
-
-            let (l2_block_vec, l1_header) = parse_block_owned(&cycle_block, channel_id);
-
-            info!("Parsed {} L2 blocks", l2_block_vec.len());
-
-            if !l2_block_vec.is_empty() {
-                block_buffer.push_front(BackfillBlockData {
-                    l2_blocks: l2_block_vec,
-                    l1_header,
-                });
-            }
-        }
-
-        Ok(BackfillData {
-            block_data: block_buffer,
-            curr_fin_l1_lib_header,
-        })
-    }
-}
-
-fn parse_block_owned(
-    l1_block: &bedrock_client::Block<SignedMantleTx>,
-    decoded_channel_id: &ChannelId,
-) -> (Vec<Block>, HeaderId) {
-    (
-        #[expect(
-            clippy::wildcard_enum_match_arm,
-            reason = "We are only interested in channel inscription ops, so it's fine to ignore the rest"
-        )]
-        l1_block
-            .transactions()
-            .flat_map(|tx| {
-                tx.mantle_tx.ops.iter().filter_map(|op| match op {
-                    Op::ChannelInscribe(InscriptionOp {
-                        channel_id,
-                        inscription,
-                        ..
-                    }) if channel_id == decoded_channel_id => {
-                        borsh::from_slice::<Block>(inscription)
-                            .inspect_err(|err| {
-                                error!("Failed to deserialize our inscription with err: {err:#?}");
-                            })
-                            .ok()
                     }
-                    _ => None,
+
-                })
+                    cursor = Some((zone_block.id, slot));
-            })
+                    if let Err(err) = self.store.set_zone_cursor(&(zone_block.id, slot)) {
-            .collect(),
+                        warn!("Failed to persist indexer cursor: {err:#}");
-        l1_block.header().id(),
+                    }
-    )
+                    yield Ok(block);
+                }
+
+                // Stream ended (caught up to LIB). Sleep then poll again.
+                tokio::time::sleep(poll_interval).await;
+            }
+        }
+    }
 }

indexer/ffi/Cargo.toml

@@ -5,9 +5,16 @@ name = "indexer_ffi"
 version = "0.1.0"
 
 [dependencies]
+nssa.workspace = true
 indexer_service.workspace = true
+indexer_service_rpc = { workspace = true, features = ["client"] }
+indexer_service_protocol.workspace = true
+
+url.workspace = true
 log = { workspace = true }
 tokio = { features = ["rt-multi-thread"], workspace = true }
+jsonrpsee.workspace = true
+anyhow.workspace = true
 
 [build-dependencies]
 cbindgen = "0.29"

indexer/ffi/indexer_ffi.h

@@ -0,0 +1,752 @@
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+typedef enum OperationStatus {
+  Ok = 0,
+  NullPointer = 1,
+  InitializationError = 2,
+  ClientError = 3,
+} OperationStatus;
+
+typedef enum FfiTransactionKind {
+  Public = 0,
+  Private,
+  ProgramDeploy,
+} FfiTransactionKind;
+
+typedef enum FfiBedrockStatus {
+  Pending = 0,
+  Safe,
+  Finalized,
+} FfiBedrockStatus;
+
+typedef struct Option_u64 Option_u64;
+
+typedef struct IndexerServiceFFI {
+  void *indexer_handle;
+  void *indexer_client;
+} IndexerServiceFFI;
+
+/**
+ * Simple wrapper around a pointer to a value or an error.
+ *
+ * Pointer is not guaranteed. You should check the error field before
+ * dereferencing the pointer.
+ */
+typedef struct PointerResult_IndexerServiceFFI__OperationStatus {
+  struct IndexerServiceFFI *value;
+  enum OperationStatus error;
+} PointerResult_IndexerServiceFFI__OperationStatus;
+
+typedef struct PointerResult_IndexerServiceFFI__OperationStatus InitializedIndexerServiceFFIResult;
+
+typedef enum PointerKind_Tag {
+  Owned,
+  Borrowed,
+  Null,
+} PointerKind_Tag;
+
+typedef struct PointerKind {
+  PointerKind_Tag tag;
+  union {
+    struct {
+      void *owned;
+    };
+    struct {
+      const void *borrowed;
+    };
+  };
+} PointerKind;
+
+typedef struct Pointer_Runtime {
+  struct PointerKind kind;
+} Pointer_Runtime;
+
+/**
+ * Wrapper around [`tokio::runtime::Runtime`] that can be safely passed across the FFI boundary.
+ */
+typedef struct Runtime {
+  struct Pointer_Runtime inner;
+} Runtime;
+
+/**
+ * Simple wrapper around a pointer to a value or an error.
+ *
+ * Pointer is not guaranteed. You should check the error field before
+ * dereferencing the pointer.
+ */
+typedef struct PointerResult_Runtime__OperationStatus {
+  struct Runtime *value;
+  enum OperationStatus error;
+} PointerResult_Runtime__OperationStatus;
+
+/**
+ * Simple wrapper around a pointer to a value or an error.
+ *
+ * Pointer is not guaranteed. You should check the error field before
+ * dereferencing the pointer.
+ */
+typedef struct PointerResult_Option_u64_____OperationStatus {
+  struct Option_u64 *value;
+  enum OperationStatus error;
+} PointerResult_Option_u64_____OperationStatus;
+
+typedef uint64_t FfiBlockId;
+
+/**
+ * 32-byte array type for `AccountId`, keys, hashes, etc.
+ */
+typedef struct FfiBytes32 {
+  uint8_t data[32];
+} FfiBytes32;
+
+typedef struct FfiBytes32 FfiHashType;
+
+typedef uint64_t FfiTimestamp;
+
+/**
+ * 64-byte array type for signatures, etc.
+ */
+typedef struct FfiBytes64 {
+  uint8_t data[64];
+} FfiBytes64;
+
+typedef struct FfiBytes64 FfiSignature;
+
+typedef struct FfiBlockHeader {
+  FfiBlockId block_id;
+  FfiHashType prev_block_hash;
+  FfiHashType hash;
+  FfiTimestamp timestamp;
+  FfiSignature signature;
+} FfiBlockHeader;
+
+/**
+ * Program ID - 8 u32 values (32 bytes total).
+ */
+typedef struct FfiProgramId {
+  uint32_t data[8];
+} FfiProgramId;
+
+typedef struct FfiBytes32 FfiAccountId;
+
+typedef struct FfiVec_FfiAccountId {
+  FfiAccountId *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_FfiAccountId;
+
+typedef struct FfiVec_FfiAccountId FfiAccountIdList;
+
+/**
+ * U128 - 16 bytes little endian.
+ */
+typedef struct FfiU128 {
+  uint8_t data[16];
+} FfiU128;
+
+typedef struct FfiU128 FfiNonce;
+
+typedef struct FfiVec_FfiNonce {
+  FfiNonce *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_FfiNonce;
+
+typedef struct FfiVec_FfiNonce FfiNonceList;
+
+typedef struct FfiVec_u32 {
+  uint32_t *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_u32;
+
+typedef struct FfiVec_u32 FfiInstructionDataList;
+
+typedef struct FfiPublicMessage {
+  struct FfiProgramId program_id;
+  FfiAccountIdList account_ids;
+  FfiNonceList nonces;
+  FfiInstructionDataList instruction_data;
+} FfiPublicMessage;
+
+typedef struct FfiBytes32 FfiPublicKey;
+
+typedef struct FfiSignaturePubKeyEntry {
+  FfiSignature signature;
+  FfiPublicKey public_key;
+} FfiSignaturePubKeyEntry;
+
+typedef struct FfiVec_FfiSignaturePubKeyEntry {
+  struct FfiSignaturePubKeyEntry *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_FfiSignaturePubKeyEntry;
+
+typedef struct FfiVec_FfiSignaturePubKeyEntry FfiSignaturePubKeyList;
+
+typedef struct FfiPublicTransactionBody {
+  FfiHashType hash;
+  struct FfiPublicMessage message;
+  FfiSignaturePubKeyList witness_set;
+} FfiPublicTransactionBody;
+
+/**
+ * Account data structure - C-compatible version of nssa Account.
+ *
+ * Note: `balance` and `nonce` are u128 values represented as little-endian
+ * byte arrays since C doesn't have native u128 support.
+ */
+typedef struct FfiAccount {
+  struct FfiProgramId program_owner;
+  /**
+   * Balance as little-endian [u8; 16].
+   */
+  struct FfiU128 balance;
+  /**
+   * Pointer to account data bytes.
+   */
+  uint8_t *data;
+  /**
+   * Length of account data.
+   */
+  uintptr_t data_len;
+  /**
+   * Capacity of account data.
+   */
+  uintptr_t data_cap;
+  /**
+   * Nonce as little-endian [u8; 16].
+   */
+  struct FfiU128 nonce;
+} FfiAccount;
+
+typedef struct FfiVec_FfiAccount {
+  struct FfiAccount *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_FfiAccount;
+
+typedef struct FfiVec_FfiAccount FfiAccountList;
+
+typedef struct FfiVec_u8 {
+  uint8_t *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_u8;
+
+typedef struct FfiVec_u8 FfiVecU8;
+
+typedef struct FfiEncryptedAccountData {
+  FfiVecU8 ciphertext;
+  FfiVecU8 epk;
+  uint8_t view_tag;
+} FfiEncryptedAccountData;
+
+typedef struct FfiVec_FfiEncryptedAccountData {
+  struct FfiEncryptedAccountData *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_FfiEncryptedAccountData;
+
+typedef struct FfiVec_FfiEncryptedAccountData FfiEncryptedAccountDataList;
+
+typedef struct FfiVec_FfiBytes32 {
+  struct FfiBytes32 *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_FfiBytes32;
+
+typedef struct FfiVec_FfiBytes32 FfiVecBytes32;
+
+typedef struct FfiNullifierCommitmentSet {
+  struct FfiBytes32 nullifier;
+  struct FfiBytes32 commitment_set_digest;
+} FfiNullifierCommitmentSet;
+
+typedef struct FfiVec_FfiNullifierCommitmentSet {
+  struct FfiNullifierCommitmentSet *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_FfiNullifierCommitmentSet;
+
+typedef struct FfiVec_FfiNullifierCommitmentSet FfiNullifierCommitmentSetList;
+
+typedef struct FfiPrivacyPreservingMessage {
+  FfiAccountIdList public_account_ids;
+  FfiNonceList nonces;
+  FfiAccountList public_post_states;
+  FfiEncryptedAccountDataList encrypted_private_post_states;
+  FfiVecBytes32 new_commitments;
+  FfiNullifierCommitmentSetList new_nullifiers;
+  uint64_t block_validity_window[2];
+  uint64_t timestamp_validity_window[2];
+} FfiPrivacyPreservingMessage;
+
+typedef FfiVecU8 FfiProof;
+
+typedef struct FfiPrivateTransactionBody {
+  FfiHashType hash;
+  struct FfiPrivacyPreservingMessage message;
+  FfiSignaturePubKeyList witness_set;
+  FfiProof proof;
+} FfiPrivateTransactionBody;
+
+typedef FfiVecU8 FfiProgramDeploymentMessage;
+
+typedef struct FfiProgramDeploymentTransactionBody {
+  FfiHashType hash;
+  FfiProgramDeploymentMessage message;
+} FfiProgramDeploymentTransactionBody;
+
+typedef struct FfiTransactionBody {
+  struct FfiPublicTransactionBody *public_body;
+  struct FfiPrivateTransactionBody *private_body;
+  struct FfiProgramDeploymentTransactionBody *program_deployment_body;
+} FfiTransactionBody;
+
+typedef struct FfiTransaction {
+  struct FfiTransactionBody body;
+  enum FfiTransactionKind kind;
+} FfiTransaction;
+
+typedef struct FfiVec_FfiTransaction {
+  struct FfiTransaction *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_FfiTransaction;
+
+typedef struct FfiVec_FfiTransaction FfiBlockBody;
+
+typedef struct FfiBytes32 FfiMsgId;
+
+typedef struct FfiBlock {
+  struct FfiBlockHeader header;
+  FfiBlockBody body;
+  enum FfiBedrockStatus bedrock_status;
+  FfiMsgId bedrock_parent_id;
+} FfiBlock;
+
+typedef struct FfiOption_FfiBlock {
+  struct FfiBlock *value;
+  bool is_some;
+} FfiOption_FfiBlock;
+
+typedef struct FfiOption_FfiBlock FfiBlockOpt;
+
+/**
+ * Simple wrapper around a pointer to a value or an error.
+ *
+ * Pointer is not guaranteed. You should check the error field before
+ * dereferencing the pointer.
+ */
+typedef struct PointerResult_FfiBlockOpt__OperationStatus {
+  FfiBlockOpt *value;
+  enum OperationStatus error;
+} PointerResult_FfiBlockOpt__OperationStatus;
+
+/**
+ * Simple wrapper around a pointer to a value or an error.
+ *
+ * Pointer is not guaranteed. You should check the error field before
+ * dereferencing the pointer.
+ */
+typedef struct PointerResult_FfiAccount__OperationStatus {
+  struct FfiAccount *value;
+  enum OperationStatus error;
+} PointerResult_FfiAccount__OperationStatus;
+
+typedef struct FfiOption_FfiTransaction {
+  struct FfiTransaction *value;
+  bool is_some;
+} FfiOption_FfiTransaction;
+
+/**
+ * Simple wrapper around a pointer to a value or an error.
+ *
+ * Pointer is not guaranteed. You should check the error field before
+ * dereferencing the pointer.
+ */
+typedef struct PointerResult_FfiOption_FfiTransaction_____OperationStatus {
+  struct FfiOption_FfiTransaction *value;
+  enum OperationStatus error;
+} PointerResult_FfiOption_FfiTransaction_____OperationStatus;
+
+typedef struct FfiVec_FfiBlock {
+  struct FfiBlock *entries;
+  uintptr_t len;
+  uintptr_t capacity;
+} FfiVec_FfiBlock;
+
+/**
+ * Simple wrapper around a pointer to a value or an error.
+ *
+ * Pointer is not guaranteed. You should check the error field before
+ * dereferencing the pointer.
+ */
+typedef struct PointerResult_FfiVec_FfiBlock_____OperationStatus {
+  struct FfiVec_FfiBlock *value;
+  enum OperationStatus error;
+} PointerResult_FfiVec_FfiBlock_____OperationStatus;
+
+typedef struct FfiOption_u64 {
+  uint64_t *value;
+  bool is_some;
+} FfiOption_u64;
+
+/**
+ * Simple wrapper around a pointer to a value or an error.
+ *
+ * Pointer is not guaranteed. You should check the error field before
+ * dereferencing the pointer.
+ */
+typedef struct PointerResult_FfiVec_FfiTransaction_____OperationStatus {
+  struct FfiVec_FfiTransaction *value;
+  enum OperationStatus error;
+} PointerResult_FfiVec_FfiTransaction_____OperationStatus;
+
+/**
+ * Creates and starts an indexer based on the provided
+ * configuration file path.
+ *
+ * # Arguments
+ *
+ * - `config_path`: A pointer to a string representing the path to the configuration file.
+ * - `port`: Number representing a port, on which indexers RPC will start.
+ *
+ * # Returns
+ *
+ * An `InitializedIndexerServiceFFIResult` containing either a pointer to the
+ * initialized `IndexerServiceFFI` or an error code.
+ *
+ * # Safety
+ * The caller must ensure that:
+ * - `runtime` is a valid pointer to a `tokio::runtime::Runtime` instance.
+ * - `config_path` is a valid pointer to a null-terminated C string.
+ */
+InitializedIndexerServiceFFIResult start_indexer(const struct Runtime *runtime,
+                                                 const char *config_path,
+                                                 uint16_t port);
+
+/**
+ * Creates a new [`tokio::runtime::Runtime`].
+ */
+struct PointerResult_Runtime__OperationStatus new_runtime(void);
+
+/**
+ * Stops and frees the resources associated with the given indexer service.
+ *
+ * # Arguments
+ *
+ * - `indexer`: A pointer to the `IndexerServiceFFI` instance to be stopped.
+ *
+ * # Returns
+ *
+ * An `OperationStatus` indicating success or failure.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `indexer` is a valid pointer to a `IndexerServiceFFI` instance
+ * - The `IndexerServiceFFI` instance was created by this library
+ * - The pointer will not be used after this function returns
+ */
+enum OperationStatus stop_indexer(struct IndexerServiceFFI *indexer);
+
+/**
+ * # Safety
+ * It's up to the caller to pass a proper pointer, if somehow from c/c++ side
+ * this is called with a type which doesn't come from a returned `CString` it
+ * will cause a segfault.
+ */
+void free_cstring(char *block);
+
+/**
+ * Query the last block id from indexer.
+ *
+ * # Arguments
+ *
+ * - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+ *
+ * # Returns
+ *
+ * A `PointerResult<Option<u64>, OperationStatus>` indicating success or failure.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `runtime` is a valid pointer to a [`Runtime`] instance.
+ * - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+ */
+struct PointerResult_Option_u64_____OperationStatus query_last_block(const struct Runtime *runtime,
+                                                                     const struct IndexerServiceFFI *indexer);
+
+/**
+ * Query the block by id from indexer.
+ *
+ * # Arguments
+ *
+ * - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+ * - `block_id`: `u64` number of block id
+ *
+ * # Returns
+ *
+ * A `PointerResult<FfiBlockOpt, OperationStatus>` indicating success or failure.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `runtime` is a valid pointer to a [`Runtime`] instance.
+ * - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+ */
+struct PointerResult_FfiBlockOpt__OperationStatus query_block(const struct Runtime *runtime,
+                                                              const struct IndexerServiceFFI *indexer,
+                                                              FfiBlockId block_id);
+
+/**
+ * Query the block by id from indexer.
+ *
+ * # Arguments
+ *
+ * - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+ * - `hash`: `FfiHashType` - hash of block
+ *
+ * # Returns
+ *
+ * A `PointerResult<FfiBlockOpt, OperationStatus>` indicating success or failure.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `runtime` is a valid pointer to a [`Runtime`] instance.
+ * - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+ */
+struct PointerResult_FfiBlockOpt__OperationStatus query_block_by_hash(const struct Runtime *runtime,
+                                                                      const struct IndexerServiceFFI *indexer,
+                                                                      FfiHashType hash);
+
+/**
+ * Query the account by id from indexer.
+ *
+ * # Arguments
+ *
+ * - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+ * - `account_id`: `FfiAccountId` - id of queried account
+ *
+ * # Returns
+ *
+ * A `PointerResult<FfiAccount, OperationStatus>` indicating success or failure.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `runtime` is a valid pointer to a [`Runtime`] instance.
+ * - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+ */
+struct PointerResult_FfiAccount__OperationStatus query_account(const struct Runtime *runtime,
+                                                               const struct IndexerServiceFFI *indexer,
+                                                               FfiAccountId account_id);
+
+/**
+ * Query the trasnaction by hash from indexer.
+ *
+ * # Arguments
+ *
+ * - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+ * - `hash`: `FfiHashType` - hash of transaction
+ *
+ * # Returns
+ *
+ * A `PointerResult<FfiOption<FfiTransaction>, OperationStatus>` indicating success or failure.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+ * - `runtime` is a valid pointer to a [`Runtime`] instance.
+ */
+struct PointerResult_FfiOption_FfiTransaction_____OperationStatus query_transaction(const struct Runtime *runtime,
+                                                                                    const struct IndexerServiceFFI *indexer,
+                                                                                    FfiHashType hash);
+
+/**
+ * Query the blocks by block range from indexer.
+ *
+ * # Arguments
+ *
+ * - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+ * - `before`: `FfiOption<u64>` - end block of query
+ * - `limit`: `u64` - number of blocks to query before `before`
+ *
+ * # Returns
+ *
+ * A `PointerResult<FfiVec<FfiBlock>, OperationStatus>` indicating success or failure.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+ * - `runtime` is a valid pointer to a [`Runtime`] instance.
+ */
+struct PointerResult_FfiVec_FfiBlock_____OperationStatus query_block_vec(const struct Runtime *runtime,
+                                                                         const struct IndexerServiceFFI *indexer,
+                                                                         struct FfiOption_u64 before,
+                                                                         uint64_t limit);
+
+/**
+ * Query the transactions range by account id from indexer.
+ *
+ * # Arguments
+ *
+ * - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+ * - `account_id`: `FfiAccountId` - id of queried account
+ * - `offset`: `u64` - first tx id of query
+ * - `limit`: `u64` - number of tx ids to query after `offset`
+ *
+ * # Returns
+ *
+ * A `PointerResult<FfiVec<FfiBlock>, OperationStatus>` indicating success or failure.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+ * - `runtime` is a valid pointer to a [`Runtime`] instance.
+ */
+struct PointerResult_FfiVec_FfiTransaction_____OperationStatus query_transactions_by_account(const struct Runtime *runtime,
+                                                                                             const struct IndexerServiceFFI *indexer,
+                                                                                             FfiAccountId account_id,
+                                                                                             uint64_t offset,
+                                                                                             uint64_t limit);
+
+/**
+ * Frees the resources associated with the given ffi account.
+ *
+ * # Arguments
+ *
+ * - `val`: An instance of `FfiAccount`.
+ *
+ * # Returns
+ *
+ * void.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `val` is a valid instance of `FfiAccount`.
+ */
+void free_ffi_account(struct FfiAccount val);
+
+/**
+ * Frees the resources associated with the given ffi block.
+ *
+ * # Arguments
+ *
+ * - `val`: An instance of `FfiBlock`.
+ *
+ * # Returns
+ *
+ * void.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `val` is a valid instance of `FfiBlock`.
+ */
+void free_ffi_block(struct FfiBlock val);
+
+/**
+ * Frees the resources associated with the given ffi block option.
+ *
+ * # Arguments
+ *
+ * - `val`: An instance of `FfiBlockOpt`.
+ *
+ * # Returns
+ *
+ * void.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `val` is a valid instance of `FfiBlockOpt`.
+ */
+void free_ffi_block_opt(FfiBlockOpt val);
+
+/**
+ * Frees the resources associated with the given ffi block vector.
+ *
+ * # Arguments
+ *
+ * - `val`: An instance of `FfiVec<FfiBlock>`.
+ *
+ * # Returns
+ *
+ * void.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `val` is a valid instance of `FfiVec<FfiBlock>`.
+ */
+void free_ffi_block_vec(struct FfiVec_FfiBlock val);
+
+/**
+ * Frees the resources associated with the given ffi transaction.
+ *
+ * # Arguments
+ *
+ * - `val`: An instance of `FfiTransaction`.
+ *
+ * # Returns
+ *
+ * void.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `val` is a valid instance of `FfiTransaction`.
+ */
+void free_ffi_transaction(struct FfiTransaction val);
+
+/**
+ * Frees the resources associated with the given ffi transaction option.
+ *
+ * # Arguments
+ *
+ * - `val`: An instance of `FfiOption<FfiTransaction>`.
+ *
+ * # Returns
+ *
+ * void.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `val` is a valid instance of `FfiOption<FfiTransaction>`.
+ */
+void free_ffi_transaction_opt(struct FfiOption_FfiTransaction val);
+
+/**
+ * Frees the resources associated with the given vector of ffi transactions.
+ *
+ * # Arguments
+ *
+ * - `val`: An instance of `FfiVec<FfiTransaction>`.
+ *
+ * # Returns
+ *
+ * void.
+ *
+ * # Safety
+ *
+ * The caller must ensure that:
+ * - `val` is a valid instance of `FfiVec<FfiTransaction>`.
+ */
+void free_ffi_transaction_vec(struct FfiVec_FfiTransaction val);
+
+bool is_ok(const enum OperationStatus *self);
+
+bool is_error(const enum OperationStatus *self);

indexer/ffi/src/api/client.rs

@@ -0,0 +1,36 @@
+use std::net::SocketAddr;
+
+use url::Url;
+
+use crate::OperationStatus;
+
+#[derive(Debug, Clone, Copy)]
+pub enum UrlProtocol {
+    Http,
+    Ws,
+}
+
+impl std::fmt::Display for UrlProtocol {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Http => write!(f, "http"),
+            Self::Ws => write!(f, "ws"),
+        }
+    }
+}
+
+pub(crate) fn addr_to_url(protocol: UrlProtocol, addr: SocketAddr) -> Result<Url, OperationStatus> {
+    // Convert 0.0.0.0 to 127.0.0.1 for client connections
+    // When binding to port 0, the server binds to 0.0.0.0:<random_port>
+    // but clients need to connect to 127.0.0.1:<port> to work reliably
+    let url_string = if addr.ip().is_unspecified() {
+        format!("{protocol}://127.0.0.1:{}", addr.port())
+    } else {
+        format!("{protocol}://{addr}")
+    };
+
+    url_string.parse().map_err(|e| {
+        log::error!("Could not parse indexer url: {e}");
+        OperationStatus::InitializationError
+    })
+}

indexer/ffi/src/api/lifecycle.rs

@@ -1,8 +1,14 @@
 use std::{ffi::c_char, path::PathBuf};
 
-use tokio::runtime::Runtime;
+use crate::{
-
+    IndexerServiceFFI, Runtime,
-use crate::{IndexerServiceFFI, api::PointerResult, errors::OperationStatus};
+    api::{
+        PointerResult,
+        client::{UrlProtocol, addr_to_url},
+    },
+    client::{IndexerClient, IndexerClientTrait as _},
+    errors::OperationStatus,
+};
 
 pub type InitializedIndexerServiceFFIResult = PointerResult<IndexerServiceFFI, OperationStatus>;
 
@@ -18,17 +24,33 @@ pub type InitializedIndexerServiceFFIResult = PointerResult<IndexerServiceFFI, O
 ///
 /// An `InitializedIndexerServiceFFIResult` containing either a pointer to the
 /// initialized `IndexerServiceFFI` or an error code.
+///
+/// # Safety
+/// The caller must ensure that:
+/// - `runtime` is a valid pointer to a `tokio::runtime::Runtime` instance.
+/// - `config_path` is a valid pointer to a null-terminated C string.
 #[unsafe(no_mangle)]
-pub extern "C" fn start_indexer(
+pub unsafe extern "C" fn start_indexer(
+    runtime: *const Runtime,
     config_path: *const c_char,
     port: u16,
 ) -> InitializedIndexerServiceFFIResult {
-    setup_indexer(config_path, port).map_or_else(
+    // SAFETY: The caller must ensure the validness of the `runtime` and `config_path` pointers.
+    unsafe { setup_indexer(runtime, config_path, port) }.map_or_else(
         InitializedIndexerServiceFFIResult::from_error,
         InitializedIndexerServiceFFIResult::from_value,
     )
 }
 
+/// Creates a new [`tokio::runtime::Runtime`].
+#[unsafe(no_mangle)]
+pub extern "C" fn new_runtime() -> PointerResult<Runtime, OperationStatus> {
+    Runtime::new().map_or_else(
+        |_e| PointerResult::from_error(OperationStatus::InitializationError),
+        PointerResult::from_value,
+    )
+}
+
 /// Initializes and starts an indexer based on the provided
 /// configuration file path.
 ///
@@ -41,7 +63,13 @@ pub extern "C" fn start_indexer(
 ///
 /// A `Result` containing either the initialized `IndexerServiceFFI` or an
 /// error code.
-fn setup_indexer(
+///
+/// # Safety
+/// The caller must ensure that:
+/// - `runtime` is a valid pointer to a `tokio::runtime::Runtime` instance.
+/// - `config_path` is a valid pointer to a null-terminated C string.
+unsafe fn setup_indexer(
+    runtime: *const Runtime,
     config_path: *const c_char,
     port: u16,
 ) -> Result<IndexerServiceFFI, OperationStatus> {
@@ -58,16 +86,26 @@ fn setup_indexer(
         OperationStatus::InitializationError
     })?;
 
-    let rt = Runtime::new().unwrap();
+    // SAFETY: The caller must ensure that `runtime` is a valid pointer to a
+    // `tokio::runtime::Runtime` instance.
+    let runtime = unsafe { &*runtime };
 
-    let indexer_handle = rt
+    let indexer_handle = runtime
         .block_on(indexer_service::run_server(config, port))
         .map_err(|e| {
             log::error!("Could not start indexer service: {e}");
             OperationStatus::InitializationError
         })?;
 
-    Ok(IndexerServiceFFI::new(indexer_handle, rt))
+    let indexer_url = addr_to_url(UrlProtocol::Ws, indexer_handle.addr())?;
+    let indexer_client = runtime
+        .block_on(IndexerClient::new(&indexer_url))
+        .map_err(|e| {
+            log::error!("Could not start indexer client: {e}");
+            OperationStatus::InitializationError
+        })?;
+
+    Ok(IndexerServiceFFI::new(indexer_handle, indexer_client))
 }
 
 /// Stops and frees the resources associated with the given indexer service.

indexer/ffi/src/api/mod.rs

@@ -1,5 +1,8 @@
 pub use result::PointerResult;
 
+pub mod client;
 pub mod lifecycle;
 pub mod memory;
+pub mod query;
 pub mod result;
+pub mod types;

indexer/ffi/src/api/query.rs

@@ -0,0 +1,348 @@
+use indexer_service_protocol::{AccountId, HashType};
+use indexer_service_rpc::RpcClient as _;
+
+use crate::{
+    IndexerServiceFFI, Runtime,
+    api::{
+        PointerResult,
+        types::{
+            FfiAccountId, FfiBlockId, FfiHashType, FfiOption, FfiVec,
+            account::FfiAccount,
+            block::{FfiBlock, FfiBlockOpt},
+            transaction::FfiTransaction,
+        },
+    },
+    errors::OperationStatus,
+};
+
+/// Query the last block id from indexer.
+///
+/// # Arguments
+///
+/// - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+///
+/// # Returns
+///
+/// A `PointerResult<Option<u64>, OperationStatus>` indicating success or failure.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `runtime` is a valid pointer to a [`Runtime`] instance.
+/// - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn query_last_block(
+    runtime: *const Runtime,
+    indexer: *const IndexerServiceFFI,
+) -> PointerResult<Option<u64>, OperationStatus> {
+    if indexer.is_null() {
+        log::error!("Attempted to query a null indexer pointer. This is a bug. Aborting.");
+        return PointerResult::from_error(OperationStatus::NullPointer);
+    }
+
+    let indexer = unsafe { &*indexer };
+
+    let client = indexer.client();
+    let runtime = unsafe { &*runtime };
+
+    runtime
+        .block_on(client.get_last_finalized_block_id())
+        .map_or_else(
+            |_| PointerResult::from_error(OperationStatus::ClientError),
+            PointerResult::from_value,
+        )
+}
+
+/// Query the block by id from indexer.
+///
+/// # Arguments
+///
+/// - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+/// - `block_id`: `u64` number of block id
+///
+/// # Returns
+///
+/// A `PointerResult<FfiBlockOpt, OperationStatus>` indicating success or failure.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `runtime` is a valid pointer to a [`Runtime`] instance.
+/// - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn query_block(
+    runtime: *const Runtime,
+    indexer: *const IndexerServiceFFI,
+    block_id: FfiBlockId,
+) -> PointerResult<FfiBlockOpt, OperationStatus> {
+    if indexer.is_null() {
+        log::error!("Attempted to query a null indexer pointer. This is a bug. Aborting.");
+        return PointerResult::from_error(OperationStatus::NullPointer);
+    }
+
+    let indexer = unsafe { &*indexer };
+
+    let client = indexer.client();
+    let runtime = unsafe { &*runtime };
+
+    runtime
+        .block_on(client.get_block_by_id(block_id))
+        .map_or_else(
+            |_| PointerResult::from_error(OperationStatus::ClientError),
+            |block_opt| {
+                let block_ffi = block_opt.map_or_else(FfiBlockOpt::from_none, |block| {
+                    FfiBlockOpt::from_value(block.into())
+                });
+
+                PointerResult::from_value(block_ffi)
+            },
+        )
+}
+
+/// Query the block by id from indexer.
+///
+/// # Arguments
+///
+/// - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+/// - `hash`: `FfiHashType` - hash of block
+///
+/// # Returns
+///
+/// A `PointerResult<FfiBlockOpt, OperationStatus>` indicating success or failure.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `runtime` is a valid pointer to a [`Runtime`] instance.
+/// - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn query_block_by_hash(
+    runtime: *const Runtime,
+    indexer: *const IndexerServiceFFI,
+    hash: FfiHashType,
+) -> PointerResult<FfiBlockOpt, OperationStatus> {
+    if indexer.is_null() {
+        log::error!("Attempted to query a null indexer pointer. This is a bug. Aborting.");
+        return PointerResult::from_error(OperationStatus::NullPointer);
+    }
+
+    let indexer = unsafe { &*indexer };
+
+    let client = indexer.client();
+    let runtime = unsafe { &*runtime };
+
+    runtime
+        .block_on(client.get_block_by_hash(HashType(hash.data)))
+        .map_or_else(
+            |_| PointerResult::from_error(OperationStatus::ClientError),
+            |block_opt| {
+                let block_ffi = block_opt.map_or_else(FfiBlockOpt::from_none, |block| {
+                    FfiBlockOpt::from_value(block.into())
+                });
+
+                PointerResult::from_value(block_ffi)
+            },
+        )
+}
+
+/// Query the account by id from indexer.
+///
+/// # Arguments
+///
+/// - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+/// - `account_id`: `FfiAccountId` - id of queried account
+///
+/// # Returns
+///
+/// A `PointerResult<FfiAccount, OperationStatus>` indicating success or failure.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `runtime` is a valid pointer to a [`Runtime`] instance.
+/// - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn query_account(
+    runtime: *const Runtime,
+    indexer: *const IndexerServiceFFI,
+    account_id: FfiAccountId,
+) -> PointerResult<FfiAccount, OperationStatus> {
+    if indexer.is_null() {
+        log::error!("Attempted to query a null indexer pointer. This is a bug. Aborting.");
+        return PointerResult::from_error(OperationStatus::NullPointer);
+    }
+
+    let indexer = unsafe { &*indexer };
+
+    let client = indexer.client();
+    let runtime = unsafe { &*runtime };
+
+    runtime
+        .block_on(client.get_account(AccountId {
+            value: account_id.data,
+        }))
+        .map_or_else(
+            |_| PointerResult::from_error(OperationStatus::ClientError),
+            |acc| {
+                let acc_nssa: nssa::Account =
+                    acc.try_into().expect("Source is in blocks, must fit");
+                PointerResult::from_value(acc_nssa.into())
+            },
+        )
+}
+
+/// Query the trasnaction by hash from indexer.
+///
+/// # Arguments
+///
+/// - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+/// - `hash`: `FfiHashType` - hash of transaction
+///
+/// # Returns
+///
+/// A `PointerResult<FfiOption<FfiTransaction>, OperationStatus>` indicating success or failure.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+/// - `runtime` is a valid pointer to a [`Runtime`] instance.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn query_transaction(
+    runtime: *const Runtime,
+    indexer: *const IndexerServiceFFI,
+    hash: FfiHashType,
+) -> PointerResult<FfiOption<FfiTransaction>, OperationStatus> {
+    if indexer.is_null() {
+        log::error!("Attempted to query a null indexer pointer. This is a bug. Aborting.");
+        return PointerResult::from_error(OperationStatus::NullPointer);
+    }
+
+    let indexer = unsafe { &*indexer };
+
+    let client = indexer.client();
+    let runtime = unsafe { &*runtime };
+
+    runtime
+        .block_on(client.get_transaction(HashType(hash.data)))
+        .map_or_else(
+            |_| PointerResult::from_error(OperationStatus::ClientError),
+            |tx_opt| {
+                let tx_ffi = tx_opt.map_or_else(FfiOption::<FfiTransaction>::from_none, |tx| {
+                    FfiOption::<FfiTransaction>::from_value(tx.into())
+                });
+
+                PointerResult::from_value(tx_ffi)
+            },
+        )
+}
+
+/// Query the blocks by block range from indexer.
+///
+/// # Arguments
+///
+/// - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+/// - `before`: `FfiOption<u64>` - end block of query
+/// - `limit`: `u64` - number of blocks to query before `before`
+///
+/// # Returns
+///
+/// A `PointerResult<FfiVec<FfiBlock>, OperationStatus>` indicating success or failure.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+/// - `runtime` is a valid pointer to a [`Runtime`] instance.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn query_block_vec(
+    runtime: *const Runtime,
+    indexer: *const IndexerServiceFFI,
+    before: FfiOption<u64>,
+    limit: u64,
+) -> PointerResult<FfiVec<FfiBlock>, OperationStatus> {
+    if indexer.is_null() {
+        log::error!("Attempted to query a null indexer pointer. This is a bug. Aborting.");
+        return PointerResult::from_error(OperationStatus::NullPointer);
+    }
+
+    let indexer = unsafe { &*indexer };
+
+    let client = indexer.client();
+    let runtime = unsafe { &*runtime };
+
+    let before_std = before.is_some.then(|| unsafe { *before.value });
+
+    runtime
+        .block_on(client.get_blocks(before_std, limit))
+        .map_or_else(
+            |_| PointerResult::from_error(OperationStatus::ClientError),
+            |block_vec| {
+                PointerResult::from_value(
+                    block_vec
+                        .into_iter()
+                        .map(Into::into)
+                        .collect::<Vec<_>>()
+                        .into(),
+                )
+            },
+        )
+}
+
+/// Query the transactions range by account id from indexer.
+///
+/// # Arguments
+///
+/// - `indexer`: A pointer to the [`IndexerServiceFFI`] instance to be queried.
+/// - `account_id`: `FfiAccountId` - id of queried account
+/// - `offset`: `u64` - first tx id of query
+/// - `limit`: `u64` - number of tx ids to query after `offset`
+///
+/// # Returns
+///
+/// A `PointerResult<FfiVec<FfiBlock>, OperationStatus>` indicating success or failure.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `indexer` is a valid pointer to a [`IndexerServiceFFI`] instance.
+/// - `runtime` is a valid pointer to a [`Runtime`] instance.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn query_transactions_by_account(
+    runtime: *const Runtime,
+    indexer: *const IndexerServiceFFI,
+    account_id: FfiAccountId,
+    offset: u64,
+    limit: u64,
+) -> PointerResult<FfiVec<FfiTransaction>, OperationStatus> {
+    if indexer.is_null() {
+        log::error!("Attempted to query a null indexer pointer. This is a bug. Aborting.");
+        return PointerResult::from_error(OperationStatus::NullPointer);
+    }
+
+    let indexer = unsafe { &*indexer };
+
+    let client = indexer.client();
+    let runtime = unsafe { &*runtime };
+
+    runtime
+        .block_on(client.get_transactions_by_account(
+            AccountId {
+                value: account_id.data,
+            },
+            offset,
+            limit,
+        ))
+        .map_or_else(
+            |_| PointerResult::from_error(OperationStatus::ClientError),
+            |tx_vec| {
+                PointerResult::from_value(
+                    tx_vec
+                        .into_iter()
+                        .map(Into::into)
+                        .collect::<Vec<_>>()
+                        .into(),
+                )
+            },
+        )
+}

indexer/ffi/src/api/types/account.rs

@@ -0,0 +1,119 @@
+use indexer_service_protocol::ProgramId;
+
+use crate::api::types::{FfiBytes32, FfiProgramId, FfiU128};
+
+/// Account data structure - C-compatible version of nssa Account.
+///
+/// Note: `balance` and `nonce` are u128 values represented as little-endian
+/// byte arrays since C doesn't have native u128 support.
+#[repr(C)]
+pub struct FfiAccount {
+    pub program_owner: FfiProgramId,
+    /// Balance as little-endian [u8; 16].
+    pub balance: FfiU128,
+    /// Pointer to account data bytes.
+    pub data: *mut u8,
+    /// Length of account data.
+    pub data_len: usize,
+    /// Capacity of account data.
+    pub data_cap: usize,
+    /// Nonce as little-endian [u8; 16].
+    pub nonce: FfiU128,
+}
+
+// Helper functions to convert between Rust and FFI types
+
+impl From<&nssa::AccountId> for FfiBytes32 {
+    fn from(id: &nssa::AccountId) -> Self {
+        Self::from_account_id(id)
+    }
+}
+
+impl From<nssa::Account> for FfiAccount {
+    fn from(value: nssa::Account) -> Self {
+        let nssa::Account {
+            program_owner,
+            balance,
+            data,
+            nonce,
+        } = value;
+
+        let (data, data_len, data_cap) = data.into_inner().into_raw_parts();
+
+        let program_owner = FfiProgramId {
+            data: program_owner,
+        };
+        Self {
+            program_owner,
+            balance: balance.into(),
+            data,
+            data_len,
+            data_cap,
+            nonce: nonce.0.into(),
+        }
+    }
+}
+
+impl From<FfiAccount> for indexer_service_protocol::Account {
+    fn from(value: FfiAccount) -> Self {
+        let FfiAccount {
+            program_owner,
+            balance,
+            data,
+            data_cap,
+            data_len,
+            nonce,
+        } = value;
+
+        Self {
+            program_owner: ProgramId(program_owner.data),
+            balance: balance.into(),
+            data: indexer_service_protocol::Data(unsafe {
+                Vec::from_raw_parts(data, data_len, data_cap)
+            }),
+            nonce: nonce.into(),
+        }
+    }
+}
+
+impl From<&FfiAccount> for indexer_service_protocol::Account {
+    fn from(value: &FfiAccount) -> Self {
+        let &FfiAccount {
+            program_owner,
+            balance,
+            data,
+            data_cap,
+            data_len,
+            nonce,
+        } = value;
+
+        Self {
+            program_owner: ProgramId(program_owner.data),
+            balance: balance.into(),
+            data: indexer_service_protocol::Data(unsafe {
+                Vec::from_raw_parts(data, data_len, data_cap)
+            }),
+            nonce: nonce.into(),
+        }
+    }
+}
+
+/// Frees the resources associated with the given ffi account.
+///
+/// # Arguments
+///
+/// - `val`: An instance of `FfiAccount`.
+///
+/// # Returns
+///
+/// void.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `val` is a valid instance of `FfiAccount`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_ffi_account(val: FfiAccount) {
+    let orig_val: indexer_service_protocol::Account = val.into();
+    drop(orig_val);
+}

indexer/ffi/src/api/types/block.rs

@@ -0,0 +1,199 @@
+use indexer_service_protocol::{
+    BedrockStatus, Block, BlockHeader, HashType, MantleMsgId, Signature,
+};
+
+use crate::api::types::{
+    FfiBlockId, FfiHashType, FfiMsgId, FfiOption, FfiSignature, FfiTimestamp, FfiVec,
+    transaction::free_ffi_transaction_vec, vectors::FfiBlockBody,
+};
+
+#[repr(C)]
+pub struct FfiBlock {
+    pub header: FfiBlockHeader,
+    pub body: FfiBlockBody,
+    pub bedrock_status: FfiBedrockStatus,
+    pub bedrock_parent_id: FfiMsgId,
+}
+
+impl From<Block> for FfiBlock {
+    fn from(value: Block) -> Self {
+        let Block {
+            header,
+            body,
+            bedrock_status,
+            bedrock_parent_id,
+        } = value;
+
+        Self {
+            header: header.into(),
+            body: body
+                .transactions
+                .into_iter()
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+            bedrock_status: bedrock_status.into(),
+            bedrock_parent_id: bedrock_parent_id.into(),
+        }
+    }
+}
+
+pub type FfiBlockOpt = FfiOption<FfiBlock>;
+
+#[repr(C)]
+pub struct FfiBlockHeader {
+    pub block_id: FfiBlockId,
+    pub prev_block_hash: FfiHashType,
+    pub hash: FfiHashType,
+    pub timestamp: FfiTimestamp,
+    pub signature: FfiSignature,
+}
+
+impl From<BlockHeader> for FfiBlockHeader {
+    fn from(value: BlockHeader) -> Self {
+        let BlockHeader {
+            block_id,
+            prev_block_hash,
+            hash,
+            timestamp,
+            signature,
+        } = value;
+
+        Self {
+            block_id,
+            prev_block_hash: prev_block_hash.into(),
+            hash: hash.into(),
+            timestamp,
+            signature: signature.into(),
+        }
+    }
+}
+
+#[repr(C)]
+pub enum FfiBedrockStatus {
+    Pending = 0x0,
+    Safe,
+    Finalized,
+}
+
+impl From<BedrockStatus> for FfiBedrockStatus {
+    fn from(value: BedrockStatus) -> Self {
+        match value {
+            BedrockStatus::Finalized => Self::Finalized,
+            BedrockStatus::Pending => Self::Pending,
+            BedrockStatus::Safe => Self::Safe,
+        }
+    }
+}
+
+impl From<FfiBedrockStatus> for BedrockStatus {
+    fn from(value: FfiBedrockStatus) -> Self {
+        match value {
+            FfiBedrockStatus::Finalized => Self::Finalized,
+            FfiBedrockStatus::Pending => Self::Pending,
+            FfiBedrockStatus::Safe => Self::Safe,
+        }
+    }
+}
+
+/// Frees the resources associated with the given ffi block.
+///
+/// # Arguments
+///
+/// - `val`: An instance of `FfiBlock`.
+///
+/// # Returns
+///
+/// void.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `val` is a valid instance of `FfiBlock`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_ffi_block(val: FfiBlock) {
+    // We don't really need all the casts, but just in case
+    // All except `ffi_tx_ffi_vec` is Copy types, so no need for Drop
+    let _ = BlockHeader {
+        block_id: val.header.block_id,
+        prev_block_hash: HashType(val.header.prev_block_hash.data),
+        hash: HashType(val.header.hash.data),
+        timestamp: val.header.timestamp,
+        signature: Signature(val.header.signature.data),
+    };
+    let ffi_tx_ffi_vec = val.body;
+
+    #[expect(clippy::let_underscore_must_use, reason = "No use for this Copy type")]
+    let _: BedrockStatus = val.bedrock_status.into();
+
+    let _ = MantleMsgId(val.bedrock_parent_id.data);
+
+    unsafe {
+        free_ffi_transaction_vec(ffi_tx_ffi_vec);
+    };
+}
+
+/// Frees the resources associated with the given ffi block option.
+///
+/// # Arguments
+///
+/// - `val`: An instance of `FfiBlockOpt`.
+///
+/// # Returns
+///
+/// void.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `val` is a valid instance of `FfiBlockOpt`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_ffi_block_opt(val: FfiBlockOpt) {
+    if val.is_some {
+        let value = unsafe { Box::from_raw(val.value) };
+
+        // We don't really need all the casts, but just in case
+        // All except `ffi_tx_ffi_vec` is Copy types, so no need for Drop
+        let _ = BlockHeader {
+            block_id: value.header.block_id,
+            prev_block_hash: HashType(value.header.prev_block_hash.data),
+            hash: HashType(value.header.hash.data),
+            timestamp: value.header.timestamp,
+            signature: Signature(value.header.signature.data),
+        };
+        let ffi_tx_ffi_vec = value.body;
+
+        #[expect(clippy::let_underscore_must_use, reason = "No use for this Copy type")]
+        let _: BedrockStatus = value.bedrock_status.into();
+
+        let _ = MantleMsgId(value.bedrock_parent_id.data);
+
+        unsafe {
+            free_ffi_transaction_vec(ffi_tx_ffi_vec);
+        };
+    }
+}
+
+/// Frees the resources associated with the given ffi block vector.
+///
+/// # Arguments
+///
+/// - `val`: An instance of `FfiVec<FfiBlock>`.
+///
+/// # Returns
+///
+/// void.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `val` is a valid instance of `FfiVec<FfiBlock>`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_ffi_block_vec(val: FfiVec<FfiBlock>) {
+    let ffi_block_std_vec: Vec<_> = val.into();
+    for block in ffi_block_std_vec {
+        unsafe {
+            free_ffi_block(block);
+        }
+    }
+}

indexer/ffi/src/api/types/mod.rs

@@ -0,0 +1,165 @@
+use indexer_service_protocol::{AccountId, HashType, MantleMsgId, ProgramId, PublicKey, Signature};
+
+pub mod account;
+pub mod block;
+pub mod transaction;
+pub mod vectors;
+
+/// 32-byte array type for `AccountId`, keys, hashes, etc.
+#[repr(C)]
+#[derive(Clone, Copy, Default)]
+pub struct FfiBytes32 {
+    pub data: [u8; 32],
+}
+
+/// 64-byte array type for signatures, etc.
+#[repr(C)]
+#[derive(Clone, Copy)]
+pub struct FfiBytes64 {
+    pub data: [u8; 64],
+}
+
+/// Program ID - 8 u32 values (32 bytes total).
+#[repr(C)]
+#[derive(Clone, Copy, Default)]
+pub struct FfiProgramId {
+    pub data: [u32; 8],
+}
+
+impl From<ProgramId> for FfiProgramId {
+    fn from(value: ProgramId) -> Self {
+        Self { data: value.0 }
+    }
+}
+
+/// U128 - 16 bytes little endian.
+#[repr(C)]
+#[derive(Clone, Copy, Default)]
+pub struct FfiU128 {
+    pub data: [u8; 16],
+}
+
+impl FfiBytes32 {
+    /// Create from a 32-byte array.
+    #[must_use]
+    pub const fn from_bytes(bytes: [u8; 32]) -> Self {
+        Self { data: bytes }
+    }
+
+    /// Create from an `AccountId`.
+    #[must_use]
+    pub const fn from_account_id(id: &nssa::AccountId) -> Self {
+        Self { data: *id.value() }
+    }
+}
+
+impl From<u128> for FfiU128 {
+    fn from(value: u128) -> Self {
+        Self {
+            data: value.to_le_bytes(),
+        }
+    }
+}
+
+impl From<FfiU128> for u128 {
+    fn from(value: FfiU128) -> Self {
+        Self::from_le_bytes(value.data)
+    }
+}
+
+pub type FfiHashType = FfiBytes32;
+pub type FfiMsgId = FfiBytes32;
+pub type FfiBlockId = u64;
+pub type FfiTimestamp = u64;
+pub type FfiSignature = FfiBytes64;
+pub type FfiAccountId = FfiBytes32;
+pub type FfiNonce = FfiU128;
+pub type FfiPublicKey = FfiBytes32;
+
+impl From<HashType> for FfiHashType {
+    fn from(value: HashType) -> Self {
+        Self { data: value.0 }
+    }
+}
+
+impl From<MantleMsgId> for FfiMsgId {
+    fn from(value: MantleMsgId) -> Self {
+        Self { data: value.0 }
+    }
+}
+
+impl From<Signature> for FfiSignature {
+    fn from(value: Signature) -> Self {
+        Self { data: value.0 }
+    }
+}
+
+impl From<AccountId> for FfiAccountId {
+    fn from(value: AccountId) -> Self {
+        Self { data: value.value }
+    }
+}
+
+impl From<PublicKey> for FfiPublicKey {
+    fn from(value: PublicKey) -> Self {
+        Self { data: value.0 }
+    }
+}
+
+#[repr(C)]
+pub struct FfiVec<T> {
+    pub entries: *mut T,
+    pub len: usize,
+    pub capacity: usize,
+}
+
+impl<T> From<Vec<T>> for FfiVec<T> {
+    fn from(value: Vec<T>) -> Self {
+        let (entries, len, capacity) = value.into_raw_parts();
+        Self {
+            entries,
+            len,
+            capacity,
+        }
+    }
+}
+
+impl<T> From<FfiVec<T>> for Vec<T> {
+    fn from(value: FfiVec<T>) -> Self {
+        unsafe { Self::from_raw_parts(value.entries, value.len, value.capacity) }
+    }
+}
+
+impl<T> FfiVec<T> {
+    /// # Safety
+    ///
+    /// `index` must be lesser than `self.len`.
+    #[must_use]
+    pub unsafe fn get(&self, index: usize) -> &T {
+        let ptr = unsafe { self.entries.add(index) };
+        unsafe { &*ptr }
+    }
+}
+
+#[repr(C)]
+pub struct FfiOption<T> {
+    pub value: *mut T,
+    pub is_some: bool,
+}
+
+impl<T> FfiOption<T> {
+    pub fn from_value(val: T) -> Self {
+        Self {
+            value: Box::into_raw(Box::new(val)),
+            is_some: true,
+        }
+    }
+
+    #[must_use]
+    pub const fn from_none() -> Self {
+        Self {
+            value: std::ptr::null_mut(),
+            is_some: false,
+        }
+    }
+}

indexer/ffi/src/api/types/transaction.rs

@@ -0,0 +1,548 @@
+use indexer_service_protocol::{
+    AccountId, Ciphertext, Commitment, CommitmentSetDigest, EncryptedAccountData,
+    EphemeralPublicKey, HashType, Nullifier, PrivacyPreservingMessage,
+    PrivacyPreservingTransaction, ProgramDeploymentMessage, ProgramDeploymentTransaction,
+    ProgramId, Proof, PublicKey, PublicMessage, PublicTransaction, Signature, Transaction,
+    ValidityWindow, WitnessSet,
+};
+
+use crate::api::types::{
+    FfiBytes32, FfiHashType, FfiOption, FfiProgramId, FfiPublicKey, FfiSignature, FfiVec,
+    vectors::{
+        FfiAccountIdList, FfiAccountList, FfiEncryptedAccountDataList, FfiInstructionDataList,
+        FfiNonceList, FfiNullifierCommitmentSetList, FfiProgramDeploymentMessage, FfiProof,
+        FfiSignaturePubKeyList, FfiVecBytes32, FfiVecU8,
+    },
+};
+
+#[repr(C)]
+pub struct FfiPublicTransactionBody {
+    pub hash: FfiHashType,
+    pub message: FfiPublicMessage,
+    pub witness_set: FfiSignaturePubKeyList,
+}
+
+impl From<PublicTransaction> for FfiPublicTransactionBody {
+    fn from(value: PublicTransaction) -> Self {
+        let PublicTransaction {
+            hash,
+            message,
+            witness_set,
+        } = value;
+
+        Self {
+            hash: hash.into(),
+            message: message.into(),
+            witness_set: witness_set
+                .signatures_and_public_keys
+                .into_iter()
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+        }
+    }
+}
+
+impl From<Box<FfiPublicTransactionBody>> for PublicTransaction {
+    fn from(value: Box<FfiPublicTransactionBody>) -> Self {
+        Self {
+            hash: HashType(value.hash.data),
+            message: PublicMessage {
+                program_id: ProgramId(value.message.program_id.data),
+                account_ids: {
+                    let std_vec: Vec<_> = value.message.account_ids.into();
+                    std_vec
+                        .into_iter()
+                        .map(|ffi_val| AccountId {
+                            value: ffi_val.data,
+                        })
+                        .collect()
+                },
+                nonces: {
+                    let std_vec: Vec<_> = value.message.nonces.into();
+                    std_vec.into_iter().map(Into::into).collect()
+                },
+                instruction_data: value.message.instruction_data.into(),
+            },
+            witness_set: WitnessSet {
+                signatures_and_public_keys: {
+                    let std_vec: Vec<_> = value.witness_set.into();
+                    std_vec
+                        .into_iter()
+                        .map(|ffi_val| {
+                            (
+                                Signature(ffi_val.signature.data),
+                                PublicKey(ffi_val.public_key.data),
+                            )
+                        })
+                        .collect()
+                },
+                proof: None,
+            },
+        }
+    }
+}
+
+#[repr(C)]
+pub struct FfiPublicMessage {
+    pub program_id: FfiProgramId,
+    pub account_ids: FfiAccountIdList,
+    pub nonces: FfiNonceList,
+    pub instruction_data: FfiInstructionDataList,
+}
+
+impl From<PublicMessage> for FfiPublicMessage {
+    fn from(value: PublicMessage) -> Self {
+        let PublicMessage {
+            program_id,
+            account_ids,
+            nonces,
+            instruction_data,
+        } = value;
+
+        Self {
+            program_id: program_id.into(),
+            account_ids: account_ids
+                .into_iter()
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+            nonces: nonces
+                .into_iter()
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+            instruction_data: instruction_data.into(),
+        }
+    }
+}
+
+#[repr(C)]
+pub struct FfiPrivateTransactionBody {
+    pub hash: FfiHashType,
+    pub message: FfiPrivacyPreservingMessage,
+    pub witness_set: FfiSignaturePubKeyList,
+    pub proof: FfiProof,
+}
+
+impl From<PrivacyPreservingTransaction> for FfiPrivateTransactionBody {
+    fn from(value: PrivacyPreservingTransaction) -> Self {
+        let PrivacyPreservingTransaction {
+            hash,
+            message,
+            witness_set,
+        } = value;
+
+        Self {
+            hash: hash.into(),
+            message: message.into(),
+            witness_set: witness_set
+                .signatures_and_public_keys
+                .into_iter()
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+            proof: witness_set
+                .proof
+                .expect("Private execution: proof must be present")
+                .0
+                .into(),
+        }
+    }
+}
+
+impl From<Box<FfiPrivateTransactionBody>> for PrivacyPreservingTransaction {
+    fn from(value: Box<FfiPrivateTransactionBody>) -> Self {
+        Self {
+            hash: HashType(value.hash.data),
+            message: PrivacyPreservingMessage {
+                public_account_ids: {
+                    let std_vec: Vec<_> = value.message.public_account_ids.into();
+                    std_vec
+                        .into_iter()
+                        .map(|ffi_val| AccountId {
+                            value: ffi_val.data,
+                        })
+                        .collect()
+                },
+                nonces: {
+                    let std_vec: Vec<_> = value.message.nonces.into();
+                    std_vec.into_iter().map(Into::into).collect()
+                },
+                public_post_states: {
+                    let std_vec: Vec<_> = value.message.public_post_states.into();
+                    std_vec.into_iter().map(Into::into).collect()
+                },
+                encrypted_private_post_states: {
+                    let std_vec: Vec<_> = value.message.encrypted_private_post_states.into();
+                    std_vec
+                        .into_iter()
+                        .map(|ffi_val| EncryptedAccountData {
+                            ciphertext: Ciphertext(ffi_val.ciphertext.into()),
+                            epk: EphemeralPublicKey(ffi_val.epk.into()),
+                            view_tag: ffi_val.view_tag,
+                        })
+                        .collect()
+                },
+                new_commitments: {
+                    let std_vec: Vec<_> = value.message.new_commitments.into();
+                    std_vec
+                        .into_iter()
+                        .map(|ffi_val| Commitment(ffi_val.data))
+                        .collect()
+                },
+                new_nullifiers: {
+                    let std_vec: Vec<_> = value.message.new_nullifiers.into();
+                    std_vec
+                        .into_iter()
+                        .map(|ffi_val| {
+                            (
+                                Nullifier(ffi_val.nullifier.data),
+                                CommitmentSetDigest(ffi_val.commitment_set_digest.data),
+                            )
+                        })
+                        .collect()
+                },
+                block_validity_window: cast_ffi_validity_window(
+                    value.message.block_validity_window,
+                ),
+                timestamp_validity_window: cast_ffi_validity_window(
+                    value.message.timestamp_validity_window,
+                ),
+            },
+            witness_set: WitnessSet {
+                signatures_and_public_keys: {
+                    let std_vec: Vec<_> = value.witness_set.into();
+                    std_vec
+                        .into_iter()
+                        .map(|ffi_val| {
+                            (
+                                Signature(ffi_val.signature.data),
+                                PublicKey(ffi_val.public_key.data),
+                            )
+                        })
+                        .collect()
+                },
+                proof: Some(Proof(value.proof.into())),
+            },
+        }
+    }
+}
+
+#[repr(C)]
+pub struct FfiPrivacyPreservingMessage {
+    pub public_account_ids: FfiAccountIdList,
+    pub nonces: FfiNonceList,
+    pub public_post_states: FfiAccountList,
+    pub encrypted_private_post_states: FfiEncryptedAccountDataList,
+    pub new_commitments: FfiVecBytes32,
+    pub new_nullifiers: FfiNullifierCommitmentSetList,
+    pub block_validity_window: [u64; 2],
+    pub timestamp_validity_window: [u64; 2],
+}
+
+impl From<PrivacyPreservingMessage> for FfiPrivacyPreservingMessage {
+    fn from(value: PrivacyPreservingMessage) -> Self {
+        let PrivacyPreservingMessage {
+            public_account_ids,
+            nonces,
+            public_post_states,
+            encrypted_private_post_states,
+            new_commitments,
+            new_nullifiers,
+            block_validity_window,
+            timestamp_validity_window,
+        } = value;
+
+        Self {
+            public_account_ids: public_account_ids
+                .into_iter()
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+            nonces: nonces
+                .into_iter()
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+            public_post_states: public_post_states
+                .into_iter()
+                .map(|acc_ind| -> nssa::Account {
+                    acc_ind.try_into().expect("Source is in blocks, must fit")
+                })
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+            encrypted_private_post_states: encrypted_private_post_states
+                .into_iter()
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+            new_commitments: new_commitments
+                .into_iter()
+                .map(|comm| FfiBytes32 { data: comm.0 })
+                .collect::<Vec<_>>()
+                .into(),
+            new_nullifiers: new_nullifiers
+                .into_iter()
+                .map(Into::into)
+                .collect::<Vec<_>>()
+                .into(),
+            block_validity_window: cast_validity_window(block_validity_window),
+            timestamp_validity_window: cast_validity_window(timestamp_validity_window),
+        }
+    }
+}
+
+#[repr(C)]
+pub struct FfiNullifierCommitmentSet {
+    pub nullifier: FfiBytes32,
+    pub commitment_set_digest: FfiBytes32,
+}
+
+impl From<(Nullifier, CommitmentSetDigest)> for FfiNullifierCommitmentSet {
+    fn from(value: (Nullifier, CommitmentSetDigest)) -> Self {
+        Self {
+            nullifier: FfiBytes32 { data: value.0.0 },
+            commitment_set_digest: FfiBytes32 { data: value.1.0 },
+        }
+    }
+}
+
+#[repr(C)]
+pub struct FfiEncryptedAccountData {
+    pub ciphertext: FfiVecU8,
+    pub epk: FfiVecU8,
+    pub view_tag: u8,
+}
+
+impl From<EncryptedAccountData> for FfiEncryptedAccountData {
+    fn from(value: EncryptedAccountData) -> Self {
+        let EncryptedAccountData {
+            ciphertext,
+            epk,
+            view_tag,
+        } = value;
+
+        Self {
+            ciphertext: ciphertext.0.into(),
+            epk: epk.0.into(),
+            view_tag,
+        }
+    }
+}
+
+#[repr(C)]
+pub struct FfiSignaturePubKeyEntry {
+    pub signature: FfiSignature,
+    pub public_key: FfiPublicKey,
+}
+
+impl From<(Signature, PublicKey)> for FfiSignaturePubKeyEntry {
+    fn from(value: (Signature, PublicKey)) -> Self {
+        Self {
+            signature: value.0.into(),
+            public_key: value.1.into(),
+        }
+    }
+}
+
+#[repr(C)]
+pub struct FfiProgramDeploymentTransactionBody {
+    pub hash: FfiHashType,
+    pub message: FfiProgramDeploymentMessage,
+}
+
+impl From<Box<FfiProgramDeploymentTransactionBody>> for ProgramDeploymentTransaction {
+    fn from(value: Box<FfiProgramDeploymentTransactionBody>) -> Self {
+        Self {
+            hash: HashType(value.hash.data),
+            message: ProgramDeploymentMessage {
+                bytecode: value.message.into(),
+            },
+        }
+    }
+}
+
+impl From<ProgramDeploymentTransaction> for FfiProgramDeploymentTransactionBody {
+    fn from(value: ProgramDeploymentTransaction) -> Self {
+        let ProgramDeploymentTransaction { hash, message } = value;
+
+        Self {
+            hash: hash.into(),
+            message: message.bytecode.into(),
+        }
+    }
+}
+
+#[repr(C)]
+pub struct FfiTransactionBody {
+    pub public_body: *mut FfiPublicTransactionBody,
+    pub private_body: *mut FfiPrivateTransactionBody,
+    pub program_deployment_body: *mut FfiProgramDeploymentTransactionBody,
+}
+
+#[repr(C)]
+pub struct FfiTransaction {
+    pub body: FfiTransactionBody,
+    pub kind: FfiTransactionKind,
+}
+
+impl From<Transaction> for FfiTransaction {
+    fn from(value: Transaction) -> Self {
+        match value {
+            Transaction::Public(pub_tx) => Self {
+                body: FfiTransactionBody {
+                    public_body: Box::into_raw(Box::new(pub_tx.into())),
+                    private_body: std::ptr::null_mut(),
+                    program_deployment_body: std::ptr::null_mut(),
+                },
+                kind: FfiTransactionKind::Public,
+            },
+            Transaction::PrivacyPreserving(priv_tx) => Self {
+                body: FfiTransactionBody {
+                    public_body: std::ptr::null_mut(),
+                    private_body: Box::into_raw(Box::new(priv_tx.into())),
+                    program_deployment_body: std::ptr::null_mut(),
+                },
+                kind: FfiTransactionKind::Private,
+            },
+            Transaction::ProgramDeployment(pr_dep_tx) => Self {
+                body: FfiTransactionBody {
+                    public_body: std::ptr::null_mut(),
+                    private_body: std::ptr::null_mut(),
+                    program_deployment_body: Box::into_raw(Box::new(pr_dep_tx.into())),
+                },
+                kind: FfiTransactionKind::ProgramDeploy,
+            },
+        }
+    }
+}
+
+#[repr(C)]
+pub enum FfiTransactionKind {
+    Public = 0x0,
+    Private,
+    ProgramDeploy,
+}
+
+/// Frees the resources associated with the given ffi transaction.
+///
+/// # Arguments
+///
+/// - `val`: An instance of `FfiTransaction`.
+///
+/// # Returns
+///
+/// void.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `val` is a valid instance of `FfiTransaction`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_ffi_transaction(val: FfiTransaction) {
+    match val.kind {
+        FfiTransactionKind::Public => {
+            let body = unsafe { Box::from_raw(val.body.public_body) };
+            let std_body: PublicTransaction = body.into();
+            drop(std_body);
+        }
+        FfiTransactionKind::Private => {
+            let body = unsafe { Box::from_raw(val.body.private_body) };
+            let std_body: PrivacyPreservingTransaction = body.into();
+            drop(std_body);
+        }
+        FfiTransactionKind::ProgramDeploy => {
+            let body = unsafe { Box::from_raw(val.body.program_deployment_body) };
+            let std_body: ProgramDeploymentTransaction = body.into();
+            drop(std_body);
+        }
+    }
+}
+
+/// Frees the resources associated with the given ffi transaction option.
+///
+/// # Arguments
+///
+/// - `val`: An instance of `FfiOption<FfiTransaction>`.
+///
+/// # Returns
+///
+/// void.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `val` is a valid instance of `FfiOption<FfiTransaction>`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_ffi_transaction_opt(val: FfiOption<FfiTransaction>) {
+    if val.is_some {
+        let value = unsafe { Box::from_raw(val.value) };
+
+        match value.kind {
+            FfiTransactionKind::Public => {
+                let body = unsafe { Box::from_raw(value.body.public_body) };
+                let std_body: PublicTransaction = body.into();
+                drop(std_body);
+            }
+            FfiTransactionKind::Private => {
+                let body = unsafe { Box::from_raw(value.body.private_body) };
+                let std_body: PrivacyPreservingTransaction = body.into();
+                drop(std_body);
+            }
+            FfiTransactionKind::ProgramDeploy => {
+                let body = unsafe { Box::from_raw(value.body.program_deployment_body) };
+                let std_body: ProgramDeploymentTransaction = body.into();
+                drop(std_body);
+            }
+        }
+    }
+}
+
+/// Frees the resources associated with the given vector of ffi transactions.
+///
+/// # Arguments
+///
+/// - `val`: An instance of `FfiVec<FfiTransaction>`.
+///
+/// # Returns
+///
+/// void.
+///
+/// # Safety
+///
+/// The caller must ensure that:
+/// - `val` is a valid instance of `FfiVec<FfiTransaction>`.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn free_ffi_transaction_vec(val: FfiVec<FfiTransaction>) {
+    let ffi_tx_std_vec: Vec<_> = val.into();
+    for tx in ffi_tx_std_vec {
+        unsafe {
+            free_ffi_transaction(tx);
+        }
+    }
+}
+
+fn cast_validity_window(window: ValidityWindow) -> [u64; 2] {
+    [
+        window.0.0.unwrap_or_default(),
+        window.0.1.unwrap_or(u64::MAX),
+    ]
+}
+
+const fn cast_ffi_validity_window(ffi_window: [u64; 2]) -> ValidityWindow {
+    let left = if ffi_window[0] == 0 {
+        None
+    } else {
+        Some(ffi_window[0])
+    };
+
+    let right = if ffi_window[1] == u64::MAX {
+        None
+    } else {
+        Some(ffi_window[1])
+    };
+
+    ValidityWindow((left, right))
+}

indexer/ffi/src/api/types/vectors.rs

@@ -0,0 +1,31 @@
+use crate::api::types::{
+    FfiAccountId, FfiBytes32, FfiNonce, FfiVec,
+    account::FfiAccount,
+    transaction::{
+        FfiEncryptedAccountData, FfiNullifierCommitmentSet, FfiSignaturePubKeyEntry, FfiTransaction,
+    },
+};
+
+pub type FfiVecU8 = FfiVec<u8>;
+
+pub type FfiAccountList = FfiVec<FfiAccount>;
+
+pub type FfiAccountIdList = FfiVec<FfiAccountId>;
+
+pub type FfiVecBytes32 = FfiVec<FfiBytes32>;
+
+pub type FfiBlockBody = FfiVec<FfiTransaction>;
+
+pub type FfiNonceList = FfiVec<FfiNonce>;
+
+pub type FfiInstructionDataList = FfiVec<u32>;
+
+pub type FfiSignaturePubKeyList = FfiVec<FfiSignaturePubKeyEntry>;
+
+pub type FfiProof = FfiVecU8;
+
+pub type FfiProgramDeploymentMessage = FfiVecU8;
+
+pub type FfiEncryptedAccountDataList = FfiVec<FfiEncryptedAccountData>;
+
+pub type FfiNullifierCommitmentSetList = FfiVec<FfiNullifierCommitmentSet>;

indexer/ffi/src/client.rs

@@ -4,7 +4,6 @@ use anyhow::{Context as _, Result};
 use log::info;
 pub use url::Url;
 
-#[expect(async_fn_in_trait, reason = "We don't care about Send/Sync here")]
 pub trait IndexerClientTrait: Clone {
     async fn new(indexer_url: &Url) -> Result<Self>;
 }

indexer/ffi/src/errors.rs

@@ -5,6 +5,7 @@ pub enum OperationStatus {
     Ok = 0x0,
     NullPointer = 0x1,
     InitializationError = 0x2,
+    ClientError = 0x3,
 }
 
 impl OperationStatus {

indexer/ffi/src/indexer.rs

@@ -0,0 +1,95 @@
+use std::{ffi::c_void, net::SocketAddr};
+
+use indexer_service::IndexerHandle;
+
+use crate::client::IndexerClient;
+
+#[repr(C)]
+pub struct IndexerServiceFFI {
+    indexer_handle: *mut c_void,
+    indexer_client: *mut c_void,
+}
+
+impl IndexerServiceFFI {
+    #[must_use]
+    pub fn new(
+        indexer_handle: indexer_service::IndexerHandle,
+        indexer_client: IndexerClient,
+    ) -> Self {
+        Self {
+            // Box the complex types and convert to opaque pointers
+            indexer_handle: Box::into_raw(Box::new(indexer_handle)).cast::<c_void>(),
+            indexer_client: Box::into_raw(Box::new(indexer_client)).cast::<c_void>(),
+        }
+    }
+
+    /// Helper to take ownership back.
+    #[must_use]
+    pub fn into_parts(mut self) -> (Box<IndexerHandle>, Box<IndexerClient>) {
+        let Self {
+            indexer_handle,
+            indexer_client,
+        } = &mut self;
+
+        let indexer_handle_boxed = unsafe { Box::from_raw(indexer_handle.cast::<IndexerHandle>()) };
+        let indexer_client_boxed = unsafe { Box::from_raw(indexer_client.cast::<IndexerClient>()) };
+
+        // Assigning nulls to prevent double free on drop, since ownership is transferred to caller
+        *indexer_handle = std::ptr::null_mut();
+        *indexer_client = std::ptr::null_mut();
+
+        (indexer_handle_boxed, indexer_client_boxed)
+    }
+
+    /// Helper to get indexer handle addr.
+    #[must_use]
+    pub const fn addr(&self) -> SocketAddr {
+        let indexer_handle = unsafe {
+            self.indexer_handle
+                .cast::<IndexerHandle>()
+                .as_ref()
+                .expect("Indexer Handle must be non-null pointer")
+        };
+
+        indexer_handle.addr()
+    }
+
+    /// Helper to get indexer handle ref.
+    #[must_use]
+    pub const fn handle(&self) -> &IndexerHandle {
+        unsafe {
+            self.indexer_handle
+                .cast::<IndexerHandle>()
+                .as_ref()
+                .expect("Indexer Handle must be non-null pointer")
+        }
+    }
+
+    /// Helper to get indexer client ref.
+    #[must_use]
+    pub const fn client(&self) -> &IndexerClient {
+        unsafe {
+            self.indexer_client
+                .cast::<IndexerClient>()
+                .as_ref()
+                .expect("Indexer Client must be non-null pointer")
+        }
+    }
+}
+
+// Implement Drop to prevent memory leaks
+impl Drop for IndexerServiceFFI {
+    fn drop(&mut self) {
+        let Self {
+            indexer_handle,
+            indexer_client,
+        } = self;
+
+        if !indexer_handle.is_null() {
+            drop(unsafe { Box::from_raw(indexer_handle.cast::<IndexerHandle>()) });
+        }
+        if !indexer_client.is_null() {
+            drop(unsafe { Box::from_raw(indexer_client.cast::<IndexerClient>()) });
+        }
+    }
+}

indexer/ffi/src/lib.rs

@@ -2,7 +2,10 @@
 
 pub use errors::OperationStatus;
 pub use indexer::IndexerServiceFFI;
+pub use runtime::Runtime;
 
 pub mod api;
+mod client;
 mod errors;
 mod indexer;
+mod runtime;