How ophelios-studio/kintsugi works
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: server Local server · contracts Rescue · tx Transaction · operations Operations
Components 20
On-chain
Solidity execution boundary for the atomic rescue transaction.
- Rescue · Main on-chain contract delegated to by the victim EOA during the EIP-7702 rescue transaction.
contracts - NonceTracker · Nonce safety and replay-control contract supporting rescue execution.
contracts - Demo mocks · 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 · Builds EIP-712 and EIP-7702 authorization payloads.
packages/core/src/auth - Discovery · Locates victim assets and account state from external sources.
packages/core/src/discovery - Operations · Turns discovered assets into ordered rescue actions.
packages/core/src/operations - Transaction · Builds gas estimates and submits the final atomic rescue transaction.
packages/core/src/tx - Core types · 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 · status, rescue, revoke, and ui command surfaces.
packages/cli/src/commands - Local server · Local API server that coordinates discovery, planning, submission, wallet, and session flows.
packages/cli/src/server - Session · Maintains local session and authorization boundaries for the CLI flow.
packages/cli/src/server/session.ts - CLI UI · 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 · Bundled step-by-step screens for welcome, wallet selection, discovery, network, plan, submit, and done.
packages/ui/src/routes - UI shell · Vite-bundled frontend shell delivered inside the CLI distribution.
packages/ui/src/App.tsx - UI API 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.
Verification
Contract and integration tests that validate rescue and anti-sweeper behavior.
- Contract tests · Rescue and NonceTracker contract tests covering batching, expiry, signatures, and chain pinning.
test/Rescue.batch.test.ts - Integration tests · 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 · Architecture, security, and usage documentation for the system and its trust boundaries.
docs/ARCHITECTURE.md
Connections 23
- 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.