nihilium-recovery-sdk 0.7.1

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "onchain"]
+	path = onchain
+	url = git@github.com:nihilium/recovery-guardian-contracts.git

package/README.md

@@ -0,0 +1,441 @@
+# Nihilium Recovery SDK
+
+Identity-gated, condition-based key recovery for self-custodial wallets, built on
+[Nihilium](https://github.com/nihilium). A wallet integrates two calls: `seal()` places a recovery
+key under a private identity condition; `recover()` returns signing authority once that condition is
+satisfied.
+
+The security comes from the settlement construction the recovered authority operates within, not from
+the SDK hiding a secret. On smart-account chains that construction is a **graduated veto** — three
+separated capabilities (pause / resume / abort), each individually harmless, held by up to three
+different parties. No veto key can move funds; completing a recovery needs the identity gate *plus* a
+matured timelock.
+
+The full specification is [`spec/nihilium-recovery-sdk.md`](spec/nihilium-recovery-sdk.md); section
+references throughout the code point at it.
+
+> **Scope: recovery covers loss, not theft.** It restores access to an owner who lost it. It does not
+> defend a wallet whose seed an attacker already holds.
+
+## Layout
+
+```
+packages/
+  core/                  chain- and protocol-agnostic: types, adapter contracts, RRS + key derivation
+  veto/                  graduated-veto state machine and config validation (the on-chain oracle)
+  shamir/                Shamir secret sharing over GF(256) (no internal dependencies)
+  nihilium/              protocol port — the ONLY package that imports @nihilium/client-sdk
+  adapters/
+    key-evm/             secp256k1
+    key-solana/          ed25519
+    condition-zkemail/   zkEmail identity gate (forked scenario, see below)
+    condition-quorum/    composite gate: any k of n member conditions
+    resolver-dkim/       TrustAnchorResolver over the DKIM registry
+    storage-local/       filesystem SealStore + add-only VaultStore
+  sdk/                   default wiring; the package wallets install
+onchain/
+  evm/                   foundry + ModuleKit; ERC-7579 executor + graduated veto
+  solana/                anchor program
+spec/
+  vectors/               frozen conformance vectors
+```
+
+`core` has no internal dependencies, and `@nihilium/client-sdk` is reachable from exactly one
+package. Both rules are enforced by `packages/core/test/boundaries.test.ts`, not just documented.
+
+`onchain/*` is deliberately **not** an npm workspace member: it installs its own dependency tree, so
+the contract toolchain stays independent of the SDK's and `forge test` never needs the TypeScript
+build.
+
+## Getting started
+
+```bash
+npm install          # TypeScript workspaces
+npm run build
+npm test             # 220 tests
+
+npm --prefix onchain/evm install     # ModuleKit's Solidity deps (separate tree)
+npm run test:evm                     # 58 tests
+```
+
+## Using it
+
+> `packages/sdk` — the preconfigured wiring a wallet would install — is **not built yet**. Today you
+> assemble the adapters yourself, which is what the examples below do. The shapes will not change
+> when that package lands; it will just pick the defaults for you.
+
+A recovery has four moving parts, and they happen at two very different times:
+
+| | At setup | At recovery |
+|---|---|---|
+| **Off-chain** (this SDK) | `seal()` puts a root secret behind the identity gate | `recover()` returns signing authority |
+| **On-chain** (the module) | install `RecoveryModule` with the veto config | initiate → timelock → execute, under veto |
+
+The off-chain half proves *who you are*. The on-chain half decides *what that lets you do, and how
+slowly*. Neither is sufficient alone, and that separation is the design.
+
+### 1 · Seal (at wallet setup)
+
+```ts
+import { RecoverySDK } from "@nihilium-recovery/core";
+import { EvmKeyAdapter, toEvmAddress } from "@nihilium-recovery/key-evm";
+import { ZKEmailConditionAdapter } from "@nihilium-recovery/condition-zkemail";
+import { LocalSealStore } from "@nihilium-recovery/storage-local";
+import {
+    NihiliumPaymentProviderClientAPIKEY_DO_NOT_USE,
+    setApiEndpoint,
+} from "@nihilium-recovery/nihilium";
+
+setApiEndpoint("https://api.nihilium.io");
+
+// Keep a reference to the adapter: `buildCondition` / `buildProof` are the adapter's, and the SDK
+// deliberately does not re-export them — the ceremony's parameters are adapter-private.
+const condition = new ZKEmailConditionAdapter({
+    emailServiceUrl: "https://zkemail.nihilium.io",
+    network: 11155111,
+    threshold: 2,        // k — processors that must cooperate to recover
+    processorCount: 3,   // n — processors sealed with
+    payment: new NihiliumPaymentProviderClientAPIKEY_DO_NOT_USE(
+        "https://api.nihilium.io",
+        process.env.NIHILIUM_API_KEY!,
+    ),
+});
+
+const sdk = new RecoverySDK({
+    key: new EvmKeyAdapter(),
+    condition,
+    sealStore: new LocalSealStore({ directory: "./seals" }),
+});
+
+const chain = {
+    namespace: "eip155:11155111",   // CAIP-2
+    tier: "smart-account" as const,
+    accountId: "0xYourSmartAccount",
+    vaultId: "wallet-1",            // one seal + one processor cohort per vault
+    epoch: 0,                       // bumped by each completed recovery
+};
+
+const { recoveryPubKey, sealBlob } = await sdk.seal({
+    condition: await condition.buildCondition({ email: "you@example.com" }),
+    chain,
+});
+
+const recoveryOwner = toEvmAddress(recoveryPubKey); // → the module's `recoveryOwner`
+```
+
+**Sealing is a paid operation** and runs a Groth16 proof per share, so it takes tens of seconds.
+`sealBlob` is a **bearer artifact**: whoever holds it can attempt a recovery, subject to the gate and
+the veto. Back it up; don't publish it.
+
+Two deliberate constraints worth knowing before you design around them:
+
+- **You cannot seal an existing private key.** `recoveryKey` accepts `{kind:"generate"}` or
+  `{kind:"rrs", rrs}` — a root secret, never a chain key. Every key is *derived* from that root plus
+  the epoch, which is what lets a completed recovery mint a fresh key without re-running (and
+  re-paying for) the ceremony. Accepting a chain key would silently turn epoch rotation back into a
+  full re-seal.
+- **`epoch` is not stored in the seal.** It is a KDF input, so rotating it costs nothing.
+
+### 2 · Install the module (once per account)
+
+`recoveryOwner` above is the address the module checks intent signatures against. It goes in
+alongside the veto config, as `onInstall` data:
+
+```solidity
+GradualVeto.Config memory veto = GradualVeto.Config({
+    pauseAuthority:     0x…,   // may pause an in-flight recovery. That is all it can do.
+    abortAuthority:     0x…,   // may kill one, irreversibly. Keep this key offline.
+    resumeMembers:      [g1, g2, g3],
+    resumeThreshold:    2,     // of resumeMembers, to lift a pause early
+    timelockSeconds:     7 days, // must elapse before the recovery is executable
+    pauseCeilingSeconds: 3 days  // a pause auto-lifts after this, so nobody can stall forever
+});
+
+account.installModule(2 /* EXECUTOR */, RECOVERY_MODULE, abi.encode(recoveryOwner, veto));
+```
+
+Hold the three veto roles separately — ideally by three different parties. Each is individually
+harmless: **no veto key can move funds**, and none of them can complete a recovery either. The
+protection comes from them being separate, so putting all three on one key throws it away while
+leaving everything looking correctly configured.
+
+`pauseCeilingSeconds` is the counterweight: a pause that never expires would be a denial-of-service on
+the legitimate owner, so a pause buys investigation time rather than a veto.
+
+### 3 · Recover (when the key is lost)
+
+```ts
+const authority = await sdk.recover({
+    proof: await condition.buildProof({ email: "you@example.com" }),
+    chain,
+    onProgress: (m) => console.log(m),
+});
+```
+
+This is **long-running and human-in-the-loop**: the service sends an email, a human must reply, and
+the proof is built from that reply. Expect minutes, not seconds.
+
+By default you get a scoped capability rather than raw bytes:
+
+```ts
+import { withCapability } from "@nihilium-recovery/core";
+
+if (authority.kind === "capability") {
+    await withCapability(authority.capability, async (cap) => {
+        const sig = await cap.sign(intentHash);   // EVM: a 32-byte digest, already hashed
+    });                                            // key wiped in `finally`, even on throw
+}
+```
+
+`{ options: { mode: "rawKey" } }` returns the bytes instead. That is a supported, first-class opt-out
+(§13), not a back door — the confinement that matters is on-chain, and holding the raw key still only
+buys you the committed rotation described below.
+
+### 4 · Drive the on-chain recovery
+
+The recovered key signs an EIP-712 `Intent` naming the account, epoch, nonce, replacement validator
+and an expiry. Every field is bound, so an intent cannot be replayed onto another account, another
+epoch, or after it goes stale.
+
+```
+initiateRecovery(intent, signature)   anyone may submit — authority is the signature, not the sender
+   │                                   (so a relayer can pay gas for a user with no funded account)
+   ├─ pause(account)                   pause authority only; INITIATED → PAUSED
+   │    └─ resume(account, …)          a threshold of distinct quorum members, or the ceiling lapses
+   ├─ abort(account)                   abort authority only; irreversible, needs no cooperation
+   ▼
+   timelockSeconds elapse → EXECUTABLE
+executeRecovery(intent)                installs the validator, bumps the epoch
+```
+
+Read the live state any time with `stateOf(account)` — it projects the clock forward, so a pause past
+its ceiling reads as `INITIATED` whether or not anyone has poked the contract.
+
+The only call this module can ever make is `installModule(TYPE_VALIDATOR, …)` on the recovering
+account. The intent chooses *which* validator; it never chooses the call shape or the target. There
+is no path through the module that moves a token. That is what makes "extracting the raw recovery key
+still only yields the committed, vetoable rotation" a property rather than an aspiration.
+
+It deliberately does **not** uninstall the superseded validator: removing a module from an ERC-7579
+sentinel list needs a correct predecessor pointer and gets the list wrong if you miss. Recovery's
+scope is loss, not theft — the old key is gone, not hostile — so that is a deliberate follow-up by
+the recovered owner.
+
+## Recovering behind k of n identities
+
+`@nihilium-recovery/condition-quorum` is a `ConditionAdapter` that wraps *other* condition adapters.
+It Shamir-splits the secret over GF(256) and places one share behind each member, so any k of n
+recover it and k-1 reveal nothing — information-theoretically, not merely computationally.
+
+Because it satisfies the ordinary `ConditionAdapter` contract, nothing else changes: `RecoverySDK`,
+the envelope, the KDF, zeroization and `SealStore` all work exactly as they do for a single member,
+and the whole quorum is **one file, stored per `vaultId`**.
+
+```ts
+import { QuorumConditionAdapter } from "@nihilium-recovery/condition-quorum";
+
+const email = new ZKEmailConditionAdapter({ /* … as in step 1 … */ });
+
+// One stateless zkEmail adapter can back every member.
+const quorum = new QuorumConditionAdapter({ members: [email, email, email] });
+
+const condition = await quorum.buildCondition({
+    threshold: 2,                                   // any 2 of the 3
+    members: [                                      // positional: entry i goes to member i
+        { email: "alice@example.com" },
+        { email: "bob@example.net" },
+        { email: "carol@example.org" },
+    ],
+});
+
+const sdk = new RecoverySDK({ key: new EvmKeyAdapter(), condition: quorum, sealStore });
+const { recoveryPubKey } = await sdk.seal({ condition, chain });   // 3 ceremonies, 1 file
+```
+
+Recovery names **exactly** the members to use, so nobody is contacted who is not needed. The named
+members run concurrently, since all of them are required:
+
+```ts
+const proof = await quorum.buildProof({
+    members: [{ index: 1 }, { index: 3 }],          // Shamir indices, 1..n
+    onProgress: (m) => console.log(m),              // prefixed "[member #1] …"
+});
+const authority = await sdk.recover({ proof, chain });
+```
+
+If a member fails, `QuorumIncompleteError` carries every member's outcome so you know who to retry
+without. Shamir is unauthenticated, so the seal also records a commitment per share and one over the
+secret: a corrupted share names its own member *before* anything is combined, rather than surfacing
+much later as an unparseable envelope after everyone has already answered their email.
+
+### Sealing costs money, so it resumes
+
+Each member is a separate paid ceremony. `onMemberSealed` checkpoints as it goes, and `resumeFrom`
+skips members already bought:
+
+```ts
+const checkpoint: QuorumMember[] = [];
+const quorum = new QuorumConditionAdapter({ members, onMemberSealed: (m) => checkpoint.push(m) });
+// … member 4 of 5 dies …
+
+const resumed = new QuorumConditionAdapter({
+    members,
+    resumeFrom: { setId, members: checkpoint },      // setId from the interrupted run
+});
+await sdk.seal({ recoveryKey: { kind: "rrs", rrs }, condition, chain });   // buys only 4 and 5
+```
+
+The split is *derived* from `(secret, setId, k, n)` rather than sampled, which is what lets a resume
+reproduce byte-identical shares without a plaintext share ever being written to disk. Supply the same
+root secret and set id; each reused member's commitment is re-checked, so resuming with the wrong
+secret fails immediately instead of writing a seal that can never reconstruct.
+
+### Two thresholds, and they are not the same
+
+`ZKEmailConditionOptions.threshold` is Nihilium's **processor** cohort — who runs one member's
+ceremony. The quorum threshold is across **members** — which identities may recover. Keep them
+distinct in anything user-facing.
+
+## One seal, several chains
+
+The KDF already separates keys by `(namespace, accountId, vaultId, epoch)`, so one root secret can
+serve many chains; a v1 envelope simply had nowhere to record more than one context. `sealMultiChain`
+records a closed set:
+
+```ts
+const { recoveryKeys } = await sdk.sealMultiChain({
+    condition,
+    contexts: [
+        { chain: evmChain,    key: new EvmKeyAdapter() },
+        { chain: solanaChain, key: new SolanaKeyAdapter() },
+    ],
+});
+```
+
+This matters most with a quorum, because members are expensive and contexts are free: two chains
+behind a 3-of-5 quorum costs **5** ceremonies, not 10. Adding a tenth chain still costs 5 — so seal a
+generous context set up front, since the set is fixed at seal time and adding one later means
+re-sealing.
+
+`recover()` is unchanged and still returns authority for exactly one chain: `parseEnvelope` selects
+the matching context and reports its algorithm, so recovering through the wrong `KeyAdapter` fails on
+the curve check rather than deriving an unrelated key. Sealing every chain at once is a convenience;
+assembling every chain's authority at once is not.
+
+## Deployments
+
+The contracts (`RecoveryModule`, `GradualVeto`), their Foundry tests, deployment script, and
+deployment records now live in
+[nihilium/recovery-guardian-contracts](https://github.com/nihilium/recovery-guardian-contracts) —
+pulled in here as a git submodule at `onchain/`, pinned to a specific reviewed commit — so they
+can be publicly audited independently of the rest of the SDK. That repo is organised per chain
+(`evm/`, with room for e.g. `solana/` later), which is why the EVM contracts land at `onchain/evm/`
+here. See that repo's README for the current live addresses on Sepolia and Arbitrum One, the
+veto-clock and settlement/proof-network
+notes, and the deployment guide.
+
+## The forked zkEmail scenario
+
+`@nihilium/client-sdk`'s `ZKEmailSealingClient` hardcodes its collection JSON, its datastream binding
+and its email-hash user input inside `create()` and `buildTemplate()`, so the machinery cannot be
+reused for a different condition graph. Rather than change nihilium-core — which backs the public
+recovery demo — the pattern is **forked** into this repo with those three lifted into parameters:
+
+| Here | Forked from | Change |
+|---|---|---|
+| `nihilium/ScenarioSealingClient` | `ZKEmailSealingClient` | collection, datastream binding and user inputs are parameters |
+| `nihilium/ScenarioUnsealingClient` | `ZKEmailUnsealingClient` | abstract base; endpoint resolution + vault decryption pulled up |
+| `condition-zkemail/ZKEmailUnsealingClient` | same | resolvers keyed per **node id**, so two-domain email (§12) works |
+| `condition-zkemail/hashEmailAddress` | `hashEmailAddress` | verbatim; pinned against upstream by a test |
+
+The upstream scenario is untouched. `condition-zkemail/test/email-hash.test.ts` compares the fork
+against `@nihilium/client-sdk` directly on every call — a drifted hash does not fail at seal time, it
+fails at recovery time as an unverifiable proof, so it is worth pinning hard.
+
+### Node compatibility
+
+`@nihilium/client-sdk` used to ship a browser-only bundle that threw on import under Node, and this
+repo carried a shim for it. As of client-sdk **0.7.1** the package ships a `node` export condition,
+the shim is gone, and `packages/nihilium/` imports it like any other dependency.
+
+Two things were wrong and both were fixed upstream rather than worked around here: the build
+resolved `snarkjs` to its browser entry (whose prover builds a worker from a `blob:` URL Node cannot
+load), and several dependencies had ESM/CJS interop that breaks under Node's resolver. Proving under
+Node is now also ~3x faster than it was through the shim, because snarkjs runs its own native path.
+
+## Testing against the live deployment
+
+Parameters mirror `../forgot-my-password-ui/.env`; see
+[`packages/adapters/condition-zkemail/.env.example`](packages/adapters/condition-zkemail/.env.example).
+Three opt-in tiers, because the costs differ sharply — `npm test` sets none of them, so the default
+suite stays hermetic and offline.
+
+| Tier | Gate | Cost |
+|---|---|---|
+| Registry + DKIM reads | `NIHILIUM_LIVE=1` | free |
+| A real k-of-n seal | `+ NIHILIUM_API_KEY` | **paid**, ~10s of proving per share |
+| A real recovery | `+ NIHILIUM_LIVE_EMAIL` | paid, and blocks on a human replying to an email |
+
+```bash
+NIHILIUM_LIVE=1 npx vitest run packages/adapters/condition-zkemail/test/live.test.ts
+```
+
+> **The public registry lists one processor.** A k-of-n seal against it exercises the threshold
+> *mechanics* — each slot still gets its own reveal value and key — but carries none of the
+> independence the threshold exists for, because one operator holds every share. The live registry
+> test warns when this is the case, so the day a second processor appears, it says so.
+
+## Two things worth knowing before you rely on this
+
+**`recover()` returns a scoped, zeroizing key — not never-assemble threshold signing.** Spec §3
+describes `SigningCapability` as threshold-signing without ever assembling the key. Nihilium's
+threshold protects a BabyJubJub *vault* scalar which is recovered whole, client-side; there is no
+threshold signer over secp256k1 or ed25519 anywhere in the protocol. What is delivered is a real but
+smaller guarantee: the key is assembled only during a recovery event, held in one closure, and wiped
+by `zeroize()`. `KeyAdapter.thresholdSign()` exists as the reserved seam and throws, naming the
+backend it needs. **User-facing copy must not claim the key is never assembled.**
+
+**A quorum seal names every guardian.** It is a bearer artifact, and each member seal carries its
+own address in the clear (the zkEmail adapter records it so a recovery needs nothing but the file).
+One stolen quorum file therefore discloses the whole recovery social graph, not just one address.
+The `Condition` summaries stay domain-only, but that is not the same as the file being private.
+
+**A multi-chain seal widens the blast radius on purpose.** Under envelope v2 a completed recovery
+yields the envelope and therefore *every* key in the context set, so §11's compartment moves from
+`(chain, account)` out to `vaultId`. It is opt-in and the context set is closed — there is no
+wildcard form — but reach for separate vaults when the chains should fail independently.
+
+**The timelock is on-chain only.** The Nihilium condition is a pure identity gate. This keeps
+pause/resume meaningful — an off-chain delay could be neither paused nor aborted — and keeps the
+state machine single-sourced.
+
+## Conformance
+
+Two frozen artefacts pin behaviour that must never drift:
+
+- **`spec/vectors/kdf.json`** — byte-exact recovery-key derivation (§11) across both curves,
+  including the length-prefix collision case that naive concatenation would get wrong. Do not
+  regenerate; a changed derivation silently strands every seal already in the wild.
+- **`spec/vectors/shamir.json`** — the GF(256) split, byte-exact, with fixed coefficients plus the
+  derived-coefficient path a resumed seal depends on. Do not regenerate; a changed split leaves the
+  shares already sitting behind each member unable to reconstruct, and nothing reveals it until
+  someone actually needs their recovery.
+- **`onchain/evm/test/fixtures/veto-traces.json`** — 200 traces generated from the TypeScript veto
+  machine and replayed against the Solidity library. The TypeScript machine is the oracle; the
+  fixture is what makes that an enforced fact rather than a comment.
+
+## Status
+
+| Phase | State |
+|---|---|
+| 0 · Scaffold + boundaries | done |
+| 1 · Core types, KDF, capability | done |
+| 2 · Storage contracts + local impl | done |
+| 3 · Veto machine + validation | done |
+| 4 · EVM contracts (ModuleKit) | done — deployed and verified on Sepolia |
+| 5 · zkEmail condition adapter | done — verified by a real 2-of-2 seal on the live set |
+| 6 · `seal()` / `recover()` over Nihilium | `seal()` verified live; `recover()` needs a human email reply to close out |
+| 7 · EVM hardened mode | partly — intent-binding and epoch invalidation already in |
+| 12 · k-of-n quorum condition | done — hermetic; not yet exercised against live ceremonies |
+| 13 · Multi-chain envelope (v2) | done — `sealMultiChain()`, v1 seals unaffected |
+| 8–11 · Solana, provider storage, demo, script tier | not started |

package/examples/quorum-recovery.mjs

@@ -0,0 +1,187 @@
+/**
+ * Runnable tour of the k-of-n quorum and the multi-chain envelope.
+ *
+ *     npm run build && node examples/quorum-recovery.mjs
+ *
+ * Everything here is the real SDK — real key adapters, real KDF, real filesystem SealStore. The one
+ * stand-in is `DemoCondition`, which replaces a live identity ceremony so this runs offline and for
+ * free. Swap it for `ZKEmailConditionAdapter` and the rest is unchanged; see `realWiring()` below.
+ */
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { RecoverySDK, withCapability } from "@nihilium-recovery/core";
+import { EvmKeyAdapter } from "@nihilium-recovery/key-evm";
+import { SolanaKeyAdapter } from "@nihilium-recovery/key-solana";
+import { LocalSealStore } from "@nihilium-recovery/storage-local";
+import {
+    QuorumConditionAdapter,
+    QuorumIncompleteError,
+    parseQuorumSeal,
+} from "@nihilium-recovery/condition-quorum";
+
+const hex = (b) => Buffer.from(b).toString("hex");
+const log = (...a) => console.log(...a);
+
+/** Stands in for a real identity ceremony. Holds the share; hands it back on demand. */
+class DemoCondition {
+    conditionType = "zkemail";
+    resolver = { rejectWeakSelectors: true, revocationFreshnessBlocks: 100,
+                 async resolve() { return { status: "valid", reason: "demo", revoked: "no", strength: "ok" }; } };
+    unreachable = false;
+    async buildCondition({ email }) {
+        return { conditionType: "zkemail", descriptor: { email },
+                 summary: `Control of an email address at ${email.split("@").pop()}` };
+    }
+    async buildProof(params = {}) { return { conditionType: "zkemail", descriptor: params }; }
+    async sealSecret({ secret }) { return { format: "demo-seal-v1", payload: hex(secret) }; }
+    async openSecret({ seal, onProgress }) {
+        if (this.unreachable) throw new Error("no reply from this mailbox");
+        onProgress?.("email answered, producing proof");
+        return Uint8Array.from(seal.payload.match(/../g).map((b) => parseInt(b, 16)));
+    }
+}
+
+const dir = mkdtempSync(join(tmpdir(), "quorum-example-"));
+const sealStore = new LocalSealStore({ directory: dir });
+
+const evmChain = {
+    namespace: "eip155:11155111", tier: "smart-account",
+    accountId: "0xAcc0", vaultId: "my-wallet", epoch: 0,
+};
+const solanaChain = {
+    namespace: "solana:mainnet", tier: "script",
+    accountId: "9xQeWvG…", vaultId: "my-wallet", epoch: 0,
+};
+
+const guardians = [
+    { email: "alice@example.com" },
+    { email: "bob@example.net" },
+    { email: "carol@example.org" },
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 1 · Seal 2-of-3
+// ─────────────────────────────────────────────────────────────────────────────
+const members = guardians.map(() => new DemoCondition());
+const quorum = new QuorumConditionAdapter({ members });
+
+const condition = await quorum.buildCondition({ threshold: 2, members: guardians });
+log("condition:", condition.summary, "\n");
+
+const key = new EvmKeyAdapter();
+const sdk = new RecoverySDK({ key, condition: quorum, sealStore });
+
+const { recoveryPubKey } = await sdk.seal({ condition, chain: evmChain });
+log("1 · sealed. register this on-chain:", hex(recoveryPubKey.bytes).slice(0, 24) + "…");
+
+const files = readdirSync(join(dir, "seals"));
+const payload = parseQuorumSeal(JSON.parse(readFileSync(join(dir, "seals", files[0]), "utf8")).blob);
+log(`    ${files.length} file on disk, holding ${payload.members.length} member seals:`);
+for (const m of payload.members) log(`      #${m.index}  ${m.summary}`);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 2 · Recover with any 2. Only the members you name are contacted.
+// ─────────────────────────────────────────────────────────────────────────────
+const proof = await quorum.buildProof({
+    members: [{ index: 1 }, { index: 3 }],
+    onProgress: (m) => log("      " + m),
+});
+log("\n2 · recovering via members #1 and #3:");
+
+const authority = await sdk.recover({ proof, chain: evmChain });
+await withCapability(authority.capability, async (cap) => {
+    const sig = await cap.sign(new Uint8Array(32).fill(1));
+    log(`    recovered ${cap.algorithm}, signed ${sig.bytes.length} bytes`);
+    log(`    matches what seal() registered:`,
+        hex(cap.publicKey.bytes) === hex(recoveryPubKey.bytes));
+});
+log("    capability zeroized:", authority.capability.zeroized);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 3 · A member that cannot be reached
+// ─────────────────────────────────────────────────────────────────────────────
+members[1].unreachable = true;
+log("\n3 · trying members #1 and #2, where #2 is unreachable:");
+try {
+    await sdk.recover({
+        proof: await quorum.buildProof({ members: [{ index: 1 }, { index: 2 }] }),
+        chain: evmChain,
+    });
+} catch (error) {
+    if (!(error instanceof QuorumIncompleteError)) throw error;
+    for (const o of error.outcomes) log(`      #${o.index} ${o.status}${o.reason ? ` — ${o.reason}` : ""}`);
+    log("    → retry with a different pair; #1's work is not wasted, unsealing is free");
+}
+members[1].unreachable = false;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 4 · One seal covering two chains (envelope v2)
+// ─────────────────────────────────────────────────────────────────────────────
+const multiDir = mkdtempSync(join(tmpdir(), "quorum-multi-"));
+const multiStore = new LocalSealStore({ directory: multiDir });
+const multiMembers = guardians.map(() => new DemoCondition());
+const multiQuorum = new QuorumConditionAdapter({ members: multiMembers });
+const multiCondition = await multiQuorum.buildCondition({ threshold: 2, members: guardians });
+
+const evmKey = new EvmKeyAdapter();
+const solanaKey = new SolanaKeyAdapter();
+const evmSdk = new RecoverySDK({ key: evmKey, condition: multiQuorum, sealStore: multiStore });
+const solanaSdk = new RecoverySDK({ key: solanaKey, condition: multiQuorum, sealStore: multiStore });
+
+const { recoveryKeys } = await evmSdk.sealMultiChain({
+    condition: multiCondition,
+    contexts: [{ chain: evmChain, key: evmKey }, { chain: solanaChain, key: solanaKey }],
+});
+log("\n4 · one seal, two chains:");
+for (const { chain, publicKey } of recoveryKeys) {
+    log(`      ${chain.namespace.padEnd(18)} ${publicKey.algorithm.padEnd(10)} ${hex(publicKey.bytes).slice(0, 20)}…`);
+}
+log(`    ${readdirSync(join(multiDir, "seals")).length} file, 3 ceremonies — not 6.`);
+
+// Each chain recovers on its own curve, through whichever guardians are available.
+const evmAuth = await evmSdk.recover({
+    proof: await multiQuorum.buildProof({ members: [{ index: 1 }, { index: 2 }] }),
+    chain: evmChain,
+});
+const solAuth = await solanaSdk.recover({
+    proof: await multiQuorum.buildProof({ members: [{ index: 2 }, { index: 3 }] }),
+    chain: solanaChain,
+});
+log("    EVM    via #1,#2 →", evmAuth.capability.algorithm,
+    hex(evmAuth.capability.publicKey.bytes) === hex(recoveryKeys[0].publicKey.bytes) ? "✓" : "✗");
+log("    Solana via #2,#3 →", solAuth.capability.algorithm,
+    hex(solAuth.capability.publicKey.bytes) === hex(recoveryKeys[1].publicKey.bytes) ? "✓" : "✗");
+evmAuth.capability.zeroize();
+solAuth.capability.zeroize();
+
+// Recovering a chain the seal never listed fails loudly rather than deriving a stranger's key.
+try {
+    await evmSdk.recover({
+        proof: await multiQuorum.buildProof({ members: [{ index: 1 }, { index: 2 }] }),
+        chain: { ...evmChain, namespace: "eip155:137" },
+    });
+} catch (error) {
+    log("    polygon (unlisted) →", error.constructor.name);
+}
+
+rmSync(dir, { recursive: true, force: true });
+rmSync(multiDir, { recursive: true, force: true });
+
+/** The only difference in production: a real condition adapter, and it costs money. */
+function realWiring() {
+    return `
+import { ZKEmailConditionAdapter } from "@nihilium-recovery/condition-zkemail";
+
+const email = new ZKEmailConditionAdapter({
+    emailServiceUrl: "https://zkemail.nihilium.io",
+    network: 11155111,
+    threshold: 2,          // Nihilium PROCESSOR cohort — not the quorum threshold
+    processorCount: 3,
+    payment,
+});
+
+// One stateless adapter can back every member.
+const quorum = new QuorumConditionAdapter({ members: [email, email, email] });
+`;
+}

package/onchain/README.md

@@ -0,0 +1,18 @@
+# recovery-guardian-contracts
+
+On-chain contracts for [nihilium-recovery-sdk](https://github.com/nihilium/recovery-sdk)'s
+recovery guardian — identity-gated, condition-based key recovery for self-custodial wallets. Kept
+in its own repo, independent of the SDK's TypeScript codebase, so the on-chain code can be
+publicly audited on its own.
+
+Recovery guardian is a per-chain concept: each chain gets its own recovery module and its own
+implementation, one directory per chain.
+
+| Directory | Chain | Status |
+|---|---|---|
+| [`evm/`](evm/) | Ethereum and other EVM chains (Foundry) | Live — deployed on Sepolia and Arbitrum One, see [`evm/README.md`](evm/README.md) |
+| `solana/` | Solana (Anchor) | Not started |
+
+`nihilium-recovery-sdk` pulls this whole repo in as a single git submodule mounted at `onchain/`,
+pinned to a specific reviewed commit rather than tracking `main`, so `onchain/evm/` here lines up
+with `onchain/evm/` there.