# ophelios-studio/kintsugi architecture

> Architecture diagram of the GitHub repository ophelios-studio/kintsugi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ophelios-studio/kintsugi
- Repository: https://github.com/ophelios-studio/kintsugi

## Overview

1. **What this repo is**
   - Kintsugi is a three-layer system for rescuing assets from a compromised EVM wallet with a single atomic EIP-7702 transaction.
   - The architecture is split between **on-chain contracts**, a **TypeScript core engine**, and two user-facing shells: a **CLI** and a bundled **web UI**.

2. **On-chain execution layer**
   - `contracts/` contains the Solidity contracts that actually perform the rescue:
     - `Rescue` is the execution contract that the victim EOA delegates to during a Type-4 / SetCode transaction.
     - `NonceTracker` supports nonce-related safety and replay control.
     - `mocks/` and `demo/` support testing and local/demo scenarios.
   - These contracts are the trust boundary for the whole system: all off-chain planning ultimately produces one transaction that must succeed inside these contracts.

3. **Core domain library**
   - `packages/core/` is the headless engine shared by CLI and UI.
   - It is organized by concern:
     - `auth/` builds the EIP-712 and EIP-7702 authorization payloads.
     - `discovery/` finds assets and account state from external sources.
     - `operations/` models the actual rescue actions for ERC-20, ERC-721, ERC-1155, ENS, and custom contract calls.
     - `tx/` assembles, estimates, and submits the final transaction.
   - This package is the main architectural boundary between “plan a rescue” and “execute a rescue.”

4. **Asset discovery pipeline**
   - Discovery starts with a victim address and produces a structured inventory of recoverable assets.
   - The repo explicitly supports several discovery sources:
     - Alchemy for wallet asset inventory.
     - Etherscan, ENS, and collection-based lookup strategies for broader coverage.
   - Discovery output feeds planning; it does not send transactions directly.

5. **Rescue planning model**
   - The `operations/` layer turns discovered assets into an ordered rescue plan.
   - Each asset type has its own operation module because the transfer semantics differ:
     - fungible tokens,
     - NFTs,
     - multi-token assets,
     - ENS records and name ownership,
     - arbitrary pre-transfer contract calls for staking, withdrawals, claims, revocations, and similar flows.
   - This is where the “batch” concept is formed before signing and submission.

6. **Transaction assembly and submission**
   - `tx/builder.ts`, `tx/gas.ts`, and `tx/submitter.ts` turn the planned operations into the final on-chain payload.
   - The design goal is one atomic rescue transaction paid entirely by the rescuer, so the victim never needs an ETH top-up.
   - This is the key anti-sweeper boundary: no intermediate funding transaction is exposed.

7. **CLI as the primary orchestration surface**
   - `packages/cli/` is the main product surface for terminal users.
   - It exposes commands for:
     - `status` for read-only inventory,
     - `rescue` for the guided rescue flow,
     - `revoke` and `ui` for related workflows.
   - The CLI is not just a thin wrapper; it coordinates configuration, session state, server startup, and the rescue workflow end to end.

8. **Local API server inside the CLI**
   - The CLI includes an embedded server under `src/server/` with route modules for:
     - discovery,
     - network selection,
     - plan generation,
     - submission,
     - wallet/session management,
     - revoke and auth flows.
   - `session.ts` and `auth.ts` indicate that the CLI maintains a local session boundary between user input, signed authorizations, and transaction submission.
   - This server is what the bundled web UI talks to when running locally.

9. **Bundled web UI**
   - `packages/ui/` is a separate React/Vite frontend that is built and then copied into the CLI distribution.
   - It provides a step-by-step rescue flow with routes for:
     - welcome,
     - wallet selection,
     - discovery,
     - network choice,
     - plan review,
     - submit,
     - done.
   - Because it is bundled into the CLI rather than published independently, the web UI is a delivery surface, not a separate product backend.

10. **Operational scripts and demo environment**
    - `scripts/` contains deployment and demo automation:
      - contract deployment,
      - test asset provisioning,
      - dry runs,
      - wallet generation,
      - a Sepolia sweeper demo.
    - `scripts/demo/` is especially important: it recreates the live anti-sweeper scenario and validates the architecture against an adversarial bot.
    - `deployments/*.json` stores deployed addresses per network, which are consumed by tooling and tests.

11. **Testing and assurance boundaries**
    - `test/` is heavily focused on contract correctness and adversarial behavior.
    - The suite includes unit tests for `Rescue` and `NonceTracker`, plus integration tests that run against Sepolia.
    - One notable structural test asserts that the victim’s ETH balance stays at zero throughout the rescue lifecycle, which directly validates the core architectural claim.
    - `test/integration/sepolia-sweeper-bypass.test.ts` proves the difference between a traditional rescue and the EIP-7702 atomic flow.

12. **Documentation and security posture**
    - `docs/ARCHITECTURE.md`, `docs/SECURITY.md`, and `docs/USAGE.md` are part of the architecture, not just marketing docs.
    - `AUDIT.md` and the README make clear that the mainnet deployment is self-audited and that security reasoning is central to the repo’s design.
    - For a diagram, the most important trust boundaries are: external discovery providers, local CLI/UI session state, off-chain signing, and the on-chain `Rescue`/`NonceTracker` execution path.

Main entry points: [`packages/cli/src/server`](https://github.com/ophelios-studio/kintsugi/tree/main/packages/cli/src/server) (Local server), [`contracts`](https://github.com/ophelios-studio/kintsugi/tree/main/contracts) (Rescue), [`packages/core/src/tx`](https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/tx) (Transaction), [`packages/core/src/operations`](https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/operations) (Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["On-chain"]
  node_contracts_rescue["Rescue<br/>Solidity executor"]
  node_contracts_nonce["NonceTracker<br/>Solidity guard"]
  node_contracts_demo_mocks["Demo mocks<br/>Solidity support"]
end

subgraph group_core["Core engine"]
  node_core_auth["Auth<br/>Payload builder"]
  node_core_discovery["Discovery<br/>Asset finder"]
  node_core_operations["Operations<br/>Plan model"]
  node_core_tx["Transaction<br/>Assembler"]
  node_core_types["Core types<br/>Shared model<br/>[types.ts]"]
end

subgraph group_cli["CLI shell"]
  node_cli_commands["Commands<br/>CLI entrypoints"]
  node_cli_server["Local server<br/>Embedded API"]
  node_cli_session["Session<br/>Local state<br/>[session.ts]"]
  node_cli_ui_helpers["CLI UI<br/>TUI helpers"]
end

subgraph group_ui["Web UI"]
  node_ui_routes["UI routes<br/>React screens"]
  node_ui_shell["UI shell<br/>React app<br/>[App.tsx]"]
  node_ui_api["UI API client<br/>Frontend client<br/>[api.ts]"]
end

subgraph group_ops["Operations"]
  node_scripts_deploy["Deploy<br/>Automation<br/>[deploy.ts]"]
  node_scripts_demo["Demo<br/>Scenario automation"]
end

subgraph group_tests["Verification"]
  node_tests_contract["Contract tests<br/>Unit suite"]
  node_tests_integration["Integration tests<br/>Sepolia suite"]
end

subgraph group_docs["Docs"]
  node_docs_arch["Architecture docs<br/>Documentation<br/>[ARCHITECTURE.md]"]
end

node_core_discovery -->|"assets"| node_core_operations
node_core_operations -->|"authorize"| node_core_auth
node_core_operations -->|"assemble"| node_core_tx
node_core_auth -->|"sign"| node_core_tx
node_core_tx -->|"submit"| node_contracts_rescue
node_core_tx -->|"replay control"| node_contracts_nonce
node_contracts_rescue -->|"checks"| node_contracts_nonce
node_cli_commands -->|"orchestrate"| node_cli_server
node_cli_server -->|"state"| node_cli_session
node_cli_server -->|"discover"| node_core_discovery
node_cli_server -->|"plan"| node_core_operations
node_cli_server -->|"submit"| node_core_tx
node_cli_server -->|"serve"| node_ui_api
node_ui_shell -->|"renders"| node_ui_routes
node_ui_routes -->|"calls"| node_ui_api
node_scripts_deploy -->|"deploys"| node_contracts_rescue
node_scripts_demo -->|"uses"| node_contracts_demo_mocks
node_tests_contract -->|"verifies"| node_contracts_rescue
node_tests_contract -->|"verifies"| node_contracts_nonce
node_tests_integration -->|"replays"| node_scripts_demo
node_tests_integration -->|"proves"| node_contracts_rescue
node_docs_arch -.->|"describes"| node_core_discovery
node_docs_arch -.->|"documents"| node_contracts_rescue

click node_contracts_rescue "https://github.com/ophelios-studio/kintsugi/tree/main/contracts"
click node_contracts_nonce "https://github.com/ophelios-studio/kintsugi/tree/main/contracts"
click node_contracts_demo_mocks "https://github.com/ophelios-studio/kintsugi/tree/main/contracts/demo"
click node_core_auth "https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/auth"
click node_core_discovery "https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/discovery"
click node_core_operations "https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/operations"
click node_core_tx "https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/tx"
click node_core_types "https://github.com/ophelios-studio/kintsugi/blob/main/packages/core/src/types.ts"
click node_cli_commands "https://github.com/ophelios-studio/kintsugi/tree/main/packages/cli/src/commands"
click node_cli_server "https://github.com/ophelios-studio/kintsugi/tree/main/packages/cli/src/server"
click node_cli_session "https://github.com/ophelios-studio/kintsugi/blob/main/packages/cli/src/server/session.ts"
click node_cli_ui_helpers "https://github.com/ophelios-studio/kintsugi/tree/main/packages/cli/src/ui"
click node_ui_routes "https://github.com/ophelios-studio/kintsugi/tree/main/packages/ui/src/routes"
click node_ui_shell "https://github.com/ophelios-studio/kintsugi/blob/main/packages/ui/src/App.tsx"
click node_ui_api "https://github.com/ophelios-studio/kintsugi/blob/main/packages/ui/src/lib/api.ts"
click node_scripts_deploy "https://github.com/ophelios-studio/kintsugi/blob/main/scripts/deploy.ts"
click node_scripts_demo "https://github.com/ophelios-studio/kintsugi/tree/main/scripts/demo"
click node_tests_contract "https://github.com/ophelios-studio/kintsugi/blob/main/test/Rescue.batch.test.ts"
click node_tests_integration "https://github.com/ophelios-studio/kintsugi/blob/main/test/integration/sepolia-sweeper-bypass.test.ts"
click node_docs_arch "https://github.com/ophelios-studio/kintsugi/blob/main/docs/ARCHITECTURE.md"

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_contracts_rescue,node_contracts_nonce,node_contracts_demo_mocks,node_docs_arch toneBlue
class node_core_auth,node_core_discovery,node_core_operations,node_core_tx,node_core_types toneAmber
class node_cli_commands,node_cli_server,node_cli_session,node_cli_ui_helpers toneMint
class node_ui_routes,node_ui_shell,node_ui_api toneRose
class node_scripts_deploy,node_scripts_demo toneIndigo
class node_tests_contract,node_tests_integration toneTeal
```

## Components

### On-chain

Solidity execution boundary for the atomic rescue transaction.

- [Rescue](https://github.com/ophelios-studio/kintsugi/tree/main/contracts): Solidity executor · Main on-chain contract delegated to by the victim EOA during the EIP-7702 rescue transaction. · `contracts`
- [NonceTracker](https://github.com/ophelios-studio/kintsugi/tree/main/contracts): Solidity guard · Nonce safety and replay-control contract supporting rescue execution. · `contracts`
- [Demo mocks](https://github.com/ophelios-studio/kintsugi/tree/main/contracts/demo): Solidity support · Demo and mock contracts used for local scenarios and testing. · `contracts/demo`

### Core engine

Shared TypeScript domain library for discovery, planning, auth, and submission.

- [Auth](https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/auth): Payload builder · Builds EIP-712 and EIP-7702 authorization payloads. · `packages/core/src/auth`
- [Discovery](https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/discovery): Asset finder · Locates victim assets and account state from external sources. · `packages/core/src/discovery`
- [Operations](https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/operations): Plan model · Turns discovered assets into ordered rescue actions. · `packages/core/src/operations`
- [Transaction](https://github.com/ophelios-studio/kintsugi/tree/main/packages/core/src/tx): Assembler · Builds gas estimates and submits the final atomic rescue transaction. · `packages/core/src/tx`
- [Core types](https://github.com/ophelios-studio/kintsugi/blob/main/packages/core/src/types.ts): Shared model · Shared domain types and constants used across the core engine. · `packages/core/src/types.ts`

### CLI shell

Terminal orchestration surface and embedded local API server.

- [Commands](https://github.com/ophelios-studio/kintsugi/tree/main/packages/cli/src/commands): CLI entrypoints · status, rescue, revoke, and ui command surfaces. · `packages/cli/src/commands`
- [Local server](https://github.com/ophelios-studio/kintsugi/tree/main/packages/cli/src/server): Embedded API · Local API server that coordinates discovery, planning, submission, wallet, and session flows. · `packages/cli/src/server`
- [Session](https://github.com/ophelios-studio/kintsugi/blob/main/packages/cli/src/server/session.ts): Local state · Maintains local session and authorization boundaries for the CLI flow. · `packages/cli/src/server/session.ts`
- [CLI UI](https://github.com/ophelios-studio/kintsugi/tree/main/packages/cli/src/ui): TUI helpers · Terminal-side presentation helpers and banners for interactive flows. · `packages/cli/src/ui`

### Web UI

Bundled React frontend consumed by the CLI server.

- [UI routes](https://github.com/ophelios-studio/kintsugi/tree/main/packages/ui/src/routes): React screens · Bundled step-by-step screens for welcome, wallet selection, discovery, network, plan, submit, and done. · `packages/ui/src/routes`
- [UI shell](https://github.com/ophelios-studio/kintsugi/blob/main/packages/ui/src/App.tsx): React app · Vite-bundled frontend shell delivered inside the CLI distribution. · `packages/ui/src/App.tsx`
- [UI API client](https://github.com/ophelios-studio/kintsugi/blob/main/packages/ui/src/lib/api.ts): Frontend client · Browser-side client used by the bundled UI to talk to the local CLI server. · `packages/ui/src/lib/api.ts`

### Operations

Automation, demos, and deployment scripts.

- [Deploy](https://github.com/ophelios-studio/kintsugi/blob/main/scripts/deploy.ts): Automation · Deployment and provisioning scripts for contracts, test assets, and wallets. · `scripts/deploy.ts`
- [Demo](https://github.com/ophelios-studio/kintsugi/tree/main/scripts/demo): Scenario automation · Adversarial demo scripts that recreate the sweeper-bypass rescue scenario. · `scripts/demo`

### Verification

Contract and integration tests that validate rescue and anti-sweeper behavior.

- [Contract tests](https://github.com/ophelios-studio/kintsugi/blob/main/test/Rescue.batch.test.ts): Unit suite · Rescue and NonceTracker contract tests covering batching, expiry, signatures, and chain pinning. · `test/Rescue.batch.test.ts`
- [Integration tests](https://github.com/ophelios-studio/kintsugi/blob/main/test/integration/sepolia-sweeper-bypass.test.ts): Sepolia suite · End-to-end tests proving the atomic EIP-7702 flow and the sweeper bypass behavior. · `test/integration/sepolia-sweeper-bypass.test.ts`

### Docs

Architecture, usage, and security documentation.

- [Architecture docs](https://github.com/ophelios-studio/kintsugi/blob/main/docs/ARCHITECTURE.md): Documentation · Architecture, security, and usage documentation for the system and its trust boundaries. · `docs/ARCHITECTURE.md`

## Connections

- Discovery → Operations: assets · Discovered inventory becomes a rescue plan.
- Operations → Auth: authorize · Planned actions are wrapped in EIP-712/EIP-7702 authorization payloads.
- Operations → Transaction: assemble · Operations are assembled into the final transaction payload.
- Auth → Transaction: sign · Authorization material is consumed by transaction assembly.
- Transaction → Rescue: submit · The assembled atomic rescue transaction targets the on-chain executor.
- Transaction → NonceTracker: replay control · Nonce safety constraints are enforced by the on-chain execution path.
- Rescue → NonceTracker: checks · Rescue execution depends on nonce tracking and replay safeguards.
- Commands → Local server: orchestrate · CLI commands drive the embedded server and workflow state.
- Local server → Session: state · The server maintains local session and authorization state.
- Local server → Discovery: discover · Discovery requests are delegated to the core engine.
- Local server → Operations: plan · Plan generation is delegated to the core engine.
- Local server → Transaction: submit · Submission flows are routed through transaction assembly and submission.
- Local server → UI API client: serve · The bundled UI talks to the local API server.
- UI shell → UI routes: renders · The UI shell hosts the step-by-step route flow.
- UI routes → UI API client: calls · Screens fetch data and advance workflow through the API client.
- Deploy → Rescue: deploys · Deployment automation prepares on-chain execution contracts.
- Demo → Demo mocks: uses · Demo automation uses mock and demo contracts for adversarial scenarios.
- Contract tests → Rescue: verifies · Unit tests exercise rescue behavior and safety invariants.
- Contract tests → NonceTracker: verifies · Unit tests exercise nonce tracking and replay control.
- Integration tests → Demo: replays · Integration tests reuse the sweeper scenario machinery.
- Integration tests → Rescue: proves · Integration tests validate the atomic rescue path against a live network scenario.
- Architecture docs → Discovery: describes · Documentation explains the discovery boundary.
- Architecture docs → Rescue: documents · Documentation records the on-chain trust boundary.