@spectre-protocol/sdk

TypeScript SDK for Spectre Protocol - ZK account recovery for AI agents on Base.

Spectre lets an agent owner recover access to their on-chain identity through one of three modes:

• Email + World ID - prove control of a registered email address (via a Noir circuit over a DKIM-signed .eml) plus a World ID proof of personhood.
• Backup wallet - recover to a pre-designated backup address.
• Social / guardians - threshold approval from a list of guardian addresses.

All recovery paths run through a configurable timelock before they can be executed.

Install

npm install @spectre-protocol/sdk viem

viem is a peer dependency. If you plan to generate proofs in the browser instead of through a hosted prover, also install:

npm install @noir-lang/noir_js @noir-lang/backend_barretenberg

Quickstart

import { SpectreClient } from "@spectre-protocol/sdk";

const client = new SpectreClient({
  rpcUrl: "https://sepolia.base.org",
  registryAddress: "0xc8458d4B3b67a9a9643d6818dC73D2a10723C551",
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
  prover: {
    type: "hosted",
    url: "http://localhost:3001",
  },
});

// Register an agent with a 10-block recovery timelock
const { hash, emailHash } = await client.register("[email protected]", 10n);

// Read state
const record = await client.getRecord(ownerAddress);
const status = await client.getRecoveryStatus(ownerAddress);

Configuration

type SpectreClientConfig = {
  rpcUrl: string;
  registryAddress: `0x${string}`;
  privateKey: `0x${string}`;
  prover:
    | { type: "hosted"; url: string }
    | { type: "browser"; circuitUrl: string };
};

• hosted - proofs are generated by an HTTP prover service (see the relayer/ server in the main repo). Lighter client, requires you to trust the prover host.
• browser - proofs are generated locally in the browser via Noir.js + barretenberg, fetched from circuitUrl. Heavier (multi-MB WASM download) but trustless.

Recovery flows

Email + World ID

import { readFile } from "fs/promises";

const eml = await readFile("recovery.eml");
const worldIdProof = JSON.parse(await readFile("worldid.json", "utf-8"));

const record = await client.getRecord(agentOwner);

// Compute the signal you need to pass into the World ID widget
const signal = client.computeSignal(agentOwner, newOwner, record.nonce);

const { hash } = await client.initiateEmailRecovery({
  eml,
  agentOwner,
  newOwner,
  nonce: record.nonce,
  worldIdProof,
});

Backup wallet

// One-time setup by the agent owner
await client.setBackupWallet(backupAddress);

// Later, signed by the backup wallet
await client.initiateBackupRecovery(agentOwner, newOwner);

Guardians

// One-time setup: 2-of-3
await client.setGuardians([g1, g2, g3], 2);

// Each guardian calls this; once `threshold` is met, recovery becomes pending
await client.approveGuardianRecovery(agentOwner, newOwner);

Finalising

After the timelock elapses:

await client.executeRecovery(agentOwner);

The agent owner can also abort an in-flight recovery at any time:

await client.cancelRecovery(agentOwner);

API reference

| Method | Purpose | |---|---| | register(email, timelockBlocks) | Register an agent under the caller's address. | | setBackupWallet(addr) | Configure the backup-wallet recovery path. | | setGuardians(addrs, threshold) | Configure the social recovery path. | | initiateEmailRecovery(params) | Start an email + World ID recovery. | | initiateBackupRecovery(owner, new) | Start a backup-wallet recovery. | | approveGuardianRecovery(owner, new) | Cast a guardian approval. | | cancelRecovery(owner) | Owner-only: abort a pending recovery. | | executeRecovery(owner) | Finalise after the timelock. | | getRecord(owner) | Read the agent's full record. | | getRecoveryStatus(owner) | Read pending recovery state and mode. | | getGuardians(owner) | List configured guardians. | | getApprovalCount(owner, new) | Current approval count for a candidate new owner. | | computeSignal(owner, new, nonce) | Compute the World ID signal for a recovery. | | computeEmailHash(email) | (via registry) keccak256 of the lowercased email. |

Networks

Currently deployed on Base Sepolia. See the main repo for current addresses.

License

MIT