# alii-hamza/setra402 architecture

> Architecture diagram of the GitHub repository alii-hamza/setra402, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alii-hamza/setra402
- Repository: https://github.com/alii-hamza/setra402

## Overview

Setra402 is a Solana escrow protocol for conditional machine-to-machine payments. The documented flow is funding an escrow, executing a task, verifying its output, then settling payment or refunding it. The checked-in runtime includes an Anchor program, TypeScript client, and facilitator verification agent; the README also describes a seller gateway and blind-voucher flow, but their implementation is not present in the tree. Edges for that undocumented wiring are therefore omitted.

Main entry points: [`programs/setra402/src/lib.rs`](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/lib.rs) (Instruction dispatch), [`programs/setra402/src/state.rs`](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/state.rs) (Task and vault PDAs), [`programs/setra402/src/instructions/settle_task_private.rs`](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/settle_task_private.rs) (Private settlement), [`sdk/src/client.ts`](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/sdk/src/client.ts) (Setra client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_participants["Task participants"]
end

subgraph group_client["Client and verification"]
  node_sdk["Setra client<br/>[client.ts]"]
  node_facilitator["Output verifier<br/>[agent.ts]"]
end

subgraph group_program["Solana escrow program"]
  node_entry["Instruction dispatch<br/>[lib.rs]"]
  node_initialize["Fund task escrow<br/>[initialize_task.rs]"]
  node_settle["Public settlement<br/>[settle_task.rs]"]
  node_private_settle["Private settlement"]
  node_cancel["Voluntary cancel<br/>[cancel_task.rs]"]
  node_refund["Timeout refund<br/>[refund_task.rs]"]
  node_task_accounts[("Task and vault PDAs<br/>[state.rs]")]
  node_nullifier_accounts[("Nullifier records<br/>[state.rs]")]
end

subgraph group_schemas["Shared account schemas"]
  node_shared_types["Shared account types<br/>[lib.rs]"]
end

node_buyer(("Buyer agent"))
node_seller(("Seller gateway"))
node_verifier(("Verifier agent"))
node_solana(("Solana RPC"))
node_spl["SPL Token program"]

node_buyer -->|"creates task"| node_sdk
node_sdk -->|"submits transactions"| node_solana
node_sdk -->|"invokes instructions"| node_entry
node_entry -->|"dispatches"| node_initialize
node_entry -->|"dispatches"| node_settle
node_entry -->|"dispatches"| node_private_settle
node_entry -->|"dispatches"| node_cancel
node_entry -->|"dispatches"| node_refund
node_initialize -->|"creates task state"| node_task_accounts
node_initialize -->|"transfers funds"| node_spl
node_settle -->|"updates status"| node_task_accounts
node_settle -->|"pays seller and fee"| node_spl
node_private_settle -->|"updates status"| node_task_accounts
node_private_settle -->|"creates record"| node_nullifier_accounts
node_private_settle -->|"pays seller and fee"| node_spl
node_cancel -->|"updates status"| node_task_accounts
node_cancel -->|"refunds and charges fee"| node_spl
node_refund -->|"updates status"| node_task_accounts
node_refund -->|"returns principal"| node_spl
node_seller -->|"returns output hash"| node_buyer
node_verifier -->|"requests verification"| node_facilitator
node_facilitator -->|"settles after match"| node_sdk
node_shared_types -.->|"mirrors schemas"| node_task_accounts

click node_sdk "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/sdk/src/client.ts"
click node_facilitator "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/facilitator/src/agent.ts"
click node_entry "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/lib.rs"
click node_initialize "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/initialize_task.rs"
click node_settle "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/settle_task.rs"
click node_private_settle "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/settle_task_private.rs"
click node_cancel "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/cancel_task.rs"
click node_refund "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/refund_task.rs"
click node_task_accounts "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/state.rs"
click node_nullifier_accounts "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/state.rs"
click node_shared_types "https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/shared/task-anchor-types/src/lib.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_sdk,node_facilitator toneAmber
class node_entry,node_initialize,node_settle,node_private_settle,node_cancel,node_refund,node_task_accounts,node_nullifier_accounts toneMint
class node_shared_types toneRose
class node_buyer,node_seller,node_verifier,node_solana,node_spl toneIndigo
```

## Components

### Client and verification

- [Setra client](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/sdk/src/client.ts): `sdk/src/client.ts`
- [Output verifier](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/facilitator/src/agent.ts): `facilitator/src/agent.ts`

### Solana escrow program

- [Instruction dispatch](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/lib.rs): `programs/setra402/src/lib.rs`
- [Fund task escrow](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/initialize_task.rs): `programs/setra402/src/instructions/initialize_task.rs`
- [Public settlement](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/settle_task.rs): `programs/setra402/src/instructions/settle_task.rs`
- [Private settlement](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/settle_task_private.rs): `programs/setra402/src/instructions/settle_task_private.rs`
- [Voluntary cancel](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/cancel_task.rs): `programs/setra402/src/instructions/cancel_task.rs`
- [Timeout refund](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/instructions/refund_task.rs): `programs/setra402/src/instructions/refund_task.rs`
- [Task and vault PDAs](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/state.rs): `programs/setra402/src/state.rs`
- [Nullifier records](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/programs/setra402/src/state.rs): `programs/setra402/src/state.rs`

### Shared account schemas

- [Shared account types](https://github.com/alii-hamza/setra402/blob/feature/chain-core-escrow/shared/task-anchor-types/src/lib.rs): `shared/task-anchor-types/src/lib.rs`

### Other components

- **Buyer agent**
- **Seller gateway**
- **Verifier agent**
- **Solana RPC**
- **SPL Token program**

## Connections

- Buyer agent → Setra client: creates task
- Setra client → Solana RPC: submits transactions
- Setra client → Instruction dispatch: invokes instructions
- Instruction dispatch → Fund task escrow: dispatches
- Instruction dispatch → Public settlement: dispatches
- Instruction dispatch → Private settlement: dispatches
- Instruction dispatch → Voluntary cancel: dispatches
- Instruction dispatch → Timeout refund: dispatches
- Fund task escrow → Task and vault PDAs: creates task state
- Fund task escrow → SPL Token program: transfers funds
- Public settlement → Task and vault PDAs: updates status
- Public settlement → SPL Token program: pays seller and fee
- Private settlement → Task and vault PDAs: updates status
- Private settlement → Nullifier records: creates record
- Private settlement → SPL Token program: pays seller and fee
- Voluntary cancel → Task and vault PDAs: updates status
- Voluntary cancel → SPL Token program: refunds and charges fee
- Timeout refund → Task and vault PDAs: updates status
- Timeout refund → SPL Token program: returns principal
- Seller gateway → Buyer agent: returns output hash
- Verifier agent → Output verifier: requests verification
- Output verifier → Setra client: settles after match
- Shared account types → Task and vault PDAs: mirrors schemas