# nori-zk/nori-solana-sdk architecture

> Architecture diagram of the GitHub repository nori-zk/nori-solana-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nori-zk/nori-solana-sdk
- Repository: https://github.com/nori-zk/nori-solana-sdk

## Overview

Nori’s bridge workflow locks ETH on Ethereum, submits proofs of Ethereum state to the Solana program, advances verified bridge state, and lets recipients claim SPL tokens. Ethereum task scripts also support deployment, fee management, and timelock administration. Generated contract bindings are shown as an internal integration layer. The proof-generation system is external; source excerpts do not establish its implementation here. The mint code describes a Merkle-witness claim, while the README flags a missing root-membership check.

Main entry points: [`programs/token/src/lib.rs`](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/lib.rs) (Program instructions), [`programs/token/src/instructions/mint.rs`](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/instructions/mint.rs) (Token minting), [`programs/token/src/instructions/update.rs`](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/instructions/update.rs) (Proof verification), [`ethereum/types/ethers-contracts/factories/TimeLockController.sol/TimelockController__factory.ts`](https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/factories/TimeLockController.sol/TimelockController__factory.ts) (Timelock factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_eth["Ethereum bridge"]
  node_eth_tasks["Bridge operations<br/>[deploy.ts]"]
end

subgraph group_client["Proof client"]
  node_proof_file["Proof file loader<br/>[proof_file.rs]"]
  node_submitter["RPC submitter<br/>[submitter.rs]"]
end

subgraph group_sol["Solana program"]
  node_program_entry["Program instructions<br/>[lib.rs]"]
  node_initialize["Bridge initialization<br/>[initialize.rs]"]
  node_bridge_state[("Bridge state<br/>[state.rs]")]
  node_proof_update["Proof verification<br/>[update.rs]"]
  node_ring_roots[("Root history<br/>[state.rs]")]
  node_witness["Deposit witness<br/>[deposit_witness.rs]"]
  node_leaf_hash["Request leaf hash"]
  node_mint["Token minting<br/>[mint.rs]"]
  node_claim_storage[("Claimed amount state<br/>[state.rs]")]
end

subgraph group_bindings["Contract bindings"]
  node_bridge_binding["Token bridge API<br/>[NoriTokenBridge.ts]"]
  node_queue_binding["Proof queue API"]
  node_timelock_binding["Timelock API"]
  node_common_types["Shared contract types<br/>[common.ts]"]
  node_bridge_factory["Bridge factory"]
  node_queue_factory["Queue factory"]
  node_timelock_factory["Timelock factory"]
end

node_depositor(("ETH depositor"))
node_proofgen(("Proof producer"))
node_claimant(("Token claimant"))
node_ethereum{{"Ethereum contracts"}}

node_depositor -->|"locks tokens"| node_ethereum
node_ethereum -.->|"proven state"| node_proofgen
node_proofgen -->|"provides proofs"| node_submitter
node_submitter -->|"submits updates"| node_program_entry
node_claimant -->|"invokes claim"| node_program_entry
node_program_entry -->|"dispatches"| node_initialize
node_program_entry -->|"dispatches"| node_proof_update
node_program_entry -->|"dispatches"| node_mint
node_initialize -->|"initializes"| node_bridge_state
node_proof_update -->|"checks and advances"| node_bridge_state
node_proof_update -->|"records roots"| node_ring_roots
node_mint -->|"checks witness"| node_witness
node_witness -->|"hashes request"| node_leaf_hash
node_mint -->|"reads bridge state"| node_bridge_state
node_mint -->|"tracks minted amount"| node_claim_storage
node_eth_tasks -->|"manages bridge"| node_ethereum
node_eth_tasks -.->|"deploys timelock"| node_timelock_factory
node_bridge_factory -->|"creates binding"| node_bridge_binding
node_queue_factory -->|"creates binding"| node_queue_binding
node_timelock_factory -->|"creates binding"| node_timelock_binding
node_bridge_factory -->|"uses types"| node_common_types
node_queue_factory -->|"uses types"| node_common_types
node_timelock_factory -->|"uses types"| node_common_types

click node_eth_tasks "https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/tasks/deploy.ts"
click node_bridge_binding "https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/NoriTokenBridge.ts"
click node_queue_binding "https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/NoriProofRequestQueue.ts"
click node_timelock_binding "https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/TimeLockController.sol/TimelockController.ts"
click node_common_types "https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/common.ts"
click node_bridge_factory "https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/factories/NoriTokenBridge__factory.ts"
click node_queue_factory "https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/factories/NoriProofRequestQueue__factory.ts"
click node_timelock_factory "https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/factories/TimeLockController.sol/TimelockController__factory.ts"
click node_proof_file "https://github.com/nori-zk/nori-solana-sdk/blob/develop/proof-submitter/src/proof_file.rs"
click node_submitter "https://github.com/nori-zk/nori-solana-sdk/blob/develop/proof-submitter/src/submitter.rs"
click node_program_entry "https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/lib.rs"
click node_initialize "https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/instructions/initialize.rs"
click node_bridge_state "https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/state.rs"
click node_proof_update "https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/instructions/update.rs"
click node_ring_roots "https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/state.rs"
click node_witness "https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/deposit_witness.rs"
click node_leaf_hash "https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/request_leaf_hash.rs"
click node_mint "https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/instructions/mint.rs"
click node_claim_storage "https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/state.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_eth_tasks toneBlue
class node_proof_file,node_submitter toneAmber
class node_program_entry,node_initialize,node_bridge_state,node_proof_update,node_ring_roots,node_witness,node_leaf_hash,node_mint,node_claim_storage toneMint
class node_bridge_binding,node_queue_binding,node_timelock_binding,node_common_types,node_bridge_factory,node_queue_factory,node_timelock_factory toneRose
class node_depositor,node_proofgen,node_claimant,node_ethereum toneIndigo
```

## Components

### Ethereum bridge

- [Bridge operations](https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/tasks/deploy.ts): `ethereum/tasks/deploy.ts`

### Proof client

- [Proof file loader](https://github.com/nori-zk/nori-solana-sdk/blob/develop/proof-submitter/src/proof_file.rs): `proof-submitter/src/proof_file.rs`
- [RPC submitter](https://github.com/nori-zk/nori-solana-sdk/blob/develop/proof-submitter/src/submitter.rs): `proof-submitter/src/submitter.rs`

### Solana program

- [Program instructions](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/lib.rs): `programs/token/src/lib.rs`
- [Bridge initialization](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/instructions/initialize.rs): `programs/token/src/instructions/initialize.rs`
- [Bridge state](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/state.rs): `programs/token/src/state.rs`
- [Proof verification](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/instructions/update.rs): `programs/token/src/instructions/update.rs`
- [Root history](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/state.rs): `programs/token/src/state.rs`
- [Deposit witness](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/deposit_witness.rs): `programs/token/src/deposit_witness.rs`
- [Request leaf hash](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/request_leaf_hash.rs): `programs/token/src/request_leaf_hash.rs`
- [Token minting](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/instructions/mint.rs): `programs/token/src/instructions/mint.rs`
- [Claimed amount state](https://github.com/nori-zk/nori-solana-sdk/blob/develop/programs/token/src/state.rs): `programs/token/src/state.rs`

### Contract bindings

- [Token bridge API](https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/NoriTokenBridge.ts): `ethereum/types/ethers-contracts/NoriTokenBridge.ts`
- [Proof queue API](https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/NoriProofRequestQueue.ts): `ethereum/types/ethers-contracts/NoriProofRequestQueue.ts`
- [Timelock API](https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/TimeLockController.sol/TimelockController.ts): `ethereum/types/ethers-contracts/TimeLockController.sol/TimelockController.ts`
- [Shared contract types](https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/common.ts): `ethereum/types/ethers-contracts/common.ts`
- [Bridge factory](https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/factories/NoriTokenBridge__factory.ts): `ethereum/types/ethers-contracts/factories/NoriTokenBridge__factory.ts`
- [Queue factory](https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/factories/NoriProofRequestQueue__factory.ts): `ethereum/types/ethers-contracts/factories/NoriProofRequestQueue__factory.ts`
- [Timelock factory](https://github.com/nori-zk/nori-solana-sdk/blob/develop/ethereum/types/ethers-contracts/factories/TimeLockController.sol/TimelockController__factory.ts): `ethereum/types/ethers-contracts/factories/TimeLockController.sol/TimelockController__factory.ts`

### Other components

- **ETH depositor**
- **Proof producer**
- **Token claimant**
- **Ethereum contracts**

## Connections

- ETH depositor → Ethereum contracts: locks tokens (evidence: `README.md`)
- Ethereum contracts → Proof producer: proven state
- Proof producer → RPC submitter: provides proofs (evidence: `README.md`)
- RPC submitter → Program instructions: submits updates (evidence: `README.md`)
- Token claimant → Program instructions: invokes claim (evidence: `README.md`)
- Program instructions → Bridge initialization: dispatches (evidence: `programs/token/src/lib.rs`)
- Program instructions → Proof verification: dispatches (evidence: `programs/token/src/lib.rs`)
- Program instructions → Token minting: dispatches (evidence: `programs/token/src/lib.rs`)
- Bridge initialization → Bridge state: initializes (evidence: `programs/token/src/instructions/initialize.rs`)
- Proof verification → Bridge state: checks and advances (evidence: `programs/token/src/instructions/update.rs`)
- Proof verification → Root history: records roots (evidence: `README.md`)
- Token minting → Deposit witness: checks witness (evidence: `programs/token/src/instructions/mint.rs`)
- Deposit witness → Request leaf hash: hashes request (evidence: `programs/token/src/deposit_witness.rs`)
- Token minting → Bridge state: reads bridge state (evidence: `programs/token/src/instructions/mint.rs`)
- Token minting → Claimed amount state: tracks minted amount (evidence: `README.md`)
- Bridge operations → Ethereum contracts: manages bridge (evidence: `README.md`)
- Bridge operations → Timelock factory: deploys timelock
- Bridge factory → Token bridge API: creates binding (evidence: `ethereum/types/ethers-contracts/factories/NoriTokenBridge__factory.ts`)
- Queue factory → Proof queue API: creates binding (evidence: `ethereum/types/ethers-contracts/factories/NoriProofRequestQueue__factory.ts`)
- Timelock factory → Timelock API: creates binding (evidence: `ethereum/types/ethers-contracts/factories/TimeLockController.sol/TimelockController__factory.ts`)
- Bridge factory → Shared contract types: uses types (evidence: `ethereum/types/ethers-contracts/factories/NoriTokenBridge__factory.ts`)
- Queue factory → Shared contract types: uses types (evidence: `ethereum/types/ethers-contracts/factories/NoriProofRequestQueue__factory.ts`)
- Timelock factory → Shared contract types: uses types (evidence: `ethereum/types/ethers-contracts/factories/TimeLockController.sol/TimelockController__factory.ts`)
