@swimmingkiim/api-sdk 0.1.35 → 0.1.37

package/dist/discovery/attestation-signer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Function signature for VC verification.
+ * Injected by the caller — can be trust-sdk's VCHandler or any custom impl.
+ */
+export type VerifyVCFunction = (vcJwt: string) => Promise<{
+    valid: boolean;
+    did: string;
+}>;
+export interface AttestationSignerOptions {
+    /** Hex-encoded secp256k1 private key of the voucher (any registered agent or bootstrap) */
+    privateKey: `0x${string}`;
+    /** Address of the deployed CredentialVerifier contract */
+    verifierContractAddress: string;
+    /** Chain ID (e.g., 8453 for Base Mainnet) */
+    chainId: number;
+    /** Injected VC verification function */
+    verifyVC: VerifyVCFunction;
+    /** Attestation validity duration in seconds (default: 3600 = 1 hour) */
+    ttlSeconds?: number;
+}
+/**
+ * Structured attestation proof ready for on-chain submission.
+ */
+export interface AttestationProof {
+    /** keccak256 hash of the verified DID */
+    didHash: `0x${string}`;
+    /** Unix timestamp after which the attestation expires */
+    deadline: bigint;
+    /** EIP-712 ECDSA signature */
+    signature: string;
+    /** Encodes the proof as ABI-packed bytes for contract submission */
+    encode: () => `0x${string}`;
+}
+/**
+ * Creates EIP-712 signed attestation proofs for the on-chain CredentialVerifier.
+ *
+ * Web of Trust: Any registered agent (or bootstrap voucher) can sign attestations
+ * to vouch for new agents. No single trusted signer required.
+ *
+ * @example
+ * ```ts
+ * import { AttestationSigner } from '@swimmingkiim/api-sdk'
+ * import { VCHandler } from '@swimmingkiim/trust-sdk'
+ *
+ * const vcHandler = new VCHandler()
+ * // Any registered agent's key can be used as voucher
+ * const signer = new AttestationSigner({
+ *     privateKey: process.env.VOUCHER_KEY as `0x${string}`,
+ *     verifierContractAddress: '0x...',
+ *     chainId: 8453,
+ *     verifyVC: async (jwt) => {
+ *         const valid = await vcHandler.verifyCredential(jwt)
+ *         const payload = JSON.parse(atob(jwt.split('.')[1]))
+ *         return { valid, did: payload.iss }
+ *     },
+ * })
+ *
+ * const proof = await signer.createAttestation(vcJwt, walletAddress)
+ * // proof.encode() → bytes for AgentRegistry.register(meta, units, proof.encode())
+ * ```
+ */
+export declare class AttestationSigner {
+    private readonly account;
+    private readonly verifierContractAddress;
+    private readonly chainId;
+    private readonly verifyVC;
+    private readonly ttlSeconds;
+    constructor(options: AttestationSignerOptions);
+    /**
+     * Verifies a VC JWT and produces a signed attestation proof.
+     *
+     * @param vcJwt - Verifiable Credential JWT string
+     * @param walletAddress - The Ethereum address of the agent being attested
+     * @returns AttestationProof with didHash, deadline, signature, and encode()
+     */
+    createAttestation(vcJwt: string, walletAddress: string): Promise<AttestationProof>;
+}
+//# sourceMappingURL=attestation-signer.d.ts.map

package/dist/discovery/attestation-signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation-signer.d.ts","sourceRoot":"","sources":["../../src/discovery/attestation-signer.ts"],"names":[],"mappings":"AAgCA;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAE1F,MAAM,WAAW,wBAAwB;IACrC,2FAA2F;IAC3F,UAAU,EAAE,KAAK,MAAM,EAAE,CAAA;IACzB,0DAA0D;IAC1D,uBAAuB,EAAE,MAAM,CAAA;IAC/B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,yCAAyC;IACzC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAA;IACtB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAA;IAChB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,oEAAoE;IACpE,MAAM,EAAE,MAAM,KAAK,MAAM,EAAE,CAAA;CAC9B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAe;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;gBAEvB,OAAO,EAAE,wBAAwB;IAU7C;;;;;;OAMG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAmD3F"}

package/dist/discovery/attestation-signer.js

@@ -0,0 +1,111 @@
+import { keccak256, toHex, encodeAbiParameters, isAddress, } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { z } from 'zod';
+// --- Validation ---
+const EthAddressSchema = z.string().refine((val) => isAddress(val), { message: 'Invalid Ethereum address format' });
+// --- EIP-712 Type Definitions (must match CredentialVerifier.sol) ---
+const EIP712_DOMAIN = {
+    name: 'CredentialVerifier',
+    version: '1',
+};
+const ATTESTATION_TYPES = {
+    Attestation: [
+        { name: 'user', type: 'address' },
+        { name: 'didHash', type: 'bytes32' },
+        { name: 'deadline', type: 'uint256' },
+    ],
+};
+const DEFAULT_TTL_SECONDS = 3600; // 1 hour
+/**
+ * Creates EIP-712 signed attestation proofs for the on-chain CredentialVerifier.
+ *
+ * Web of Trust: Any registered agent (or bootstrap voucher) can sign attestations
+ * to vouch for new agents. No single trusted signer required.
+ *
+ * @example
+ * ```ts
+ * import { AttestationSigner } from '@swimmingkiim/api-sdk'
+ * import { VCHandler } from '@swimmingkiim/trust-sdk'
+ *
+ * const vcHandler = new VCHandler()
+ * // Any registered agent's key can be used as voucher
+ * const signer = new AttestationSigner({
+ *     privateKey: process.env.VOUCHER_KEY as `0x${string}`,
+ *     verifierContractAddress: '0x...',
+ *     chainId: 8453,
+ *     verifyVC: async (jwt) => {
+ *         const valid = await vcHandler.verifyCredential(jwt)
+ *         const payload = JSON.parse(atob(jwt.split('.')[1]))
+ *         return { valid, did: payload.iss }
+ *     },
+ * })
+ *
+ * const proof = await signer.createAttestation(vcJwt, walletAddress)
+ * // proof.encode() → bytes for AgentRegistry.register(meta, units, proof.encode())
+ * ```
+ */
+export class AttestationSigner {
+    account;
+    verifierContractAddress;
+    chainId;
+    verifyVC;
+    ttlSeconds;
+    constructor(options) {
+        EthAddressSchema.parse(options.verifierContractAddress);
+        this.account = privateKeyToAccount(options.privateKey);
+        this.verifierContractAddress = options.verifierContractAddress;
+        this.chainId = options.chainId;
+        this.verifyVC = options.verifyVC;
+        this.ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    }
+    /**
+     * Verifies a VC JWT and produces a signed attestation proof.
+     *
+     * @param vcJwt - Verifiable Credential JWT string
+     * @param walletAddress - The Ethereum address of the agent being attested
+     * @returns AttestationProof with didHash, deadline, signature, and encode()
+     */
+    async createAttestation(vcJwt, walletAddress) {
+        // 1. Validate wallet address
+        EthAddressSchema.parse(walletAddress);
+        // 2. Verify VC
+        const { valid, did } = await this.verifyVC(vcJwt);
+        if (!valid) {
+            throw new Error('VC verification failed');
+        }
+        // 3. Hash the DID for nullifier
+        const didHash = keccak256(toHex(did));
+        // 4. Calculate deadline
+        const deadline = BigInt(Math.floor(Date.now() / 1000) + this.ttlSeconds);
+        if (!this.account.signTypedData) {
+            throw new Error('Account does not support signTypedData');
+        }
+        // 5. Sign EIP-712 typed data
+        const signature = await this.account.signTypedData({
+            domain: {
+                ...EIP712_DOMAIN,
+                chainId: this.chainId,
+                verifyingContract: this.verifierContractAddress,
+            },
+            types: ATTESTATION_TYPES,
+            primaryType: 'Attestation',
+            message: {
+                user: walletAddress,
+                didHash,
+                deadline,
+            },
+        });
+        // 6. Return structured proof
+        return {
+            didHash,
+            deadline,
+            signature,
+            encode: () => encodeAbiParameters([
+                { name: 'didHash', type: 'bytes32' },
+                { name: 'deadline', type: 'uint256' },
+                { name: 'signature', type: 'bytes' },
+            ], [didHash, deadline, signature]),
+        };
+    }
+}
+//# sourceMappingURL=attestation-signer.js.map

package/dist/discovery/attestation-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation-signer.js","sourceRoot":"","sources":["../../src/discovery/attestation-signer.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from './mcp-server.js';
 export * from './discovery/llms-reader.js';
 export * from './discovery/registry-reader.js';
+export * from './discovery/attestation-signer.js';
+export * from './quantum-client.js';
 export * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gCAAgC,CAAA;AAC9C,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gCAAgC,CAAA;AAC9C,cAAc,mCAAmC,CAAA;AACjD,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -1,5 +1,7 @@
 export * from './mcp-server.js';
 export * from './discovery/llms-reader.js';
 export * from './discovery/registry-reader.js';
+export * from './discovery/attestation-signer.js';
+export * from './quantum-client.js';
 export * from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gCAAgC,CAAA;AAC9C,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gCAAgC,CAAA;AAC9C,cAAc,mCAAmC,CAAA;AACjD,cAAc,qBAAqB,CAAA;AACnC,cAAc,YAAY,CAAA"}

package/dist/quantum-client.d.ts

@@ -0,0 +1,49 @@
+import { Address } from 'viem';
+export interface QuantumClientOptions {
+    rpcUrl: string;
+    contractAddress: Address;
+    baseBackoffMs?: number;
+    maxBackoffMs?: number;
+    maxRetries?: number;
+}
+export declare class OverheatedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Client for interacting with the QuantumTaskBuffer smart contract.
+ * Implements V_AI (Self-Restraint) by structurally enforcing an exponential backoff
+ * when the macroscopic system is detected as 'overheated'.
+ */
+export declare class QuantumTaskClient {
+    private publicClient;
+    private contractAddress;
+    private baseBackoffMs;
+    private maxBackoffMs;
+    private maxRetries;
+    constructor(options: QuantumClientOptions);
+    /**
+     * Checks the thermodynamic state of the buffer.
+     * @returns boolean true if the system pending tasks exceed CRITICAL_MASS.
+     */
+    isOverheated(): Promise<boolean>;
+    /**
+     * Sleep helper for backoff
+     */
+    private sleep;
+    /**
+     * Prepares the `submitTask` transaction call data, enforcing V_AI (Thermodynamic Throttling).
+     * The agent SDK intrinsically checks the `isOverheated` state. If the system is overheated,
+     * the SDK *refuses* to generate the transaction and applies an exponential backoff.
+     *
+     * @param complexityHash The unique hash of the task logic to submit.
+     * @param metadataUri The URI (e.g. ipfs://...) pointing to the standard JSON metadata.
+     * @returns The call data object for use with the Paymaster or standard transaction execution.
+     * @throws OverheatedError if max retries are exceeded while the system remains overheated.
+     */
+    enforceThrottleAndGetTaskCall(complexityHash: bigint, metadataUri: string): Promise<{
+        to: Address;
+        value: bigint;
+        data: string;
+    }>;
+}
+//# sourceMappingURL=quantum-client.d.ts.map

package/dist/quantum-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quantum-client.d.ts","sourceRoot":"","sources":["../src/quantum-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyC,OAAO,EAAgB,MAAM,MAAM,CAAC;AAoCpF,MAAM,WAAW,oBAAoB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,eAAgB,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI9B;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,eAAe,CAAU;IACjC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,oBAAoB;IAUzC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC;IAetC;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;;;;;;;;OASG;IACG,6BAA6B,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAyC1I"}

package/dist/quantum-client.js

@@ -0,0 +1,127 @@
+import { createPublicClient, http, getContract } from 'viem';
+const QUANTUM_TASK_BUFFER_ABI = [
+    {
+        "inputs": [],
+        "name": "isOverheated",
+        "outputs": [
+            {
+                "internalType": "bool",
+                "name": "",
+                "type": "bool"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
+    {
+        "inputs": [
+            {
+                "internalType": "uint256",
+                "name": "_complexityHash",
+                "type": "uint256"
+            },
+            {
+                "internalType": "string",
+                "name": "_metadataUri",
+                "type": "string"
+            }
+        ],
+        "name": "submitTask",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+    }
+];
+export class OverheatedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OverheatedError';
+    }
+}
+/**
+ * Client for interacting with the QuantumTaskBuffer smart contract.
+ * Implements V_AI (Self-Restraint) by structurally enforcing an exponential backoff
+ * when the macroscopic system is detected as 'overheated'.
+ */
+export class QuantumTaskClient {
+    publicClient;
+    contractAddress;
+    baseBackoffMs;
+    maxBackoffMs;
+    maxRetries;
+    constructor(options) {
+        this.publicClient = createPublicClient({
+            transport: http(options.rpcUrl),
+        });
+        this.contractAddress = options.contractAddress;
+        this.baseBackoffMs = options.baseBackoffMs || 30_000; // 30 seconds default
+        this.maxBackoffMs = options.maxBackoffMs || 600_000; // 10 mins default
+        this.maxRetries = options.maxRetries || 5;
+    }
+    /**
+     * Checks the thermodynamic state of the buffer.
+     * @returns boolean true if the system pending tasks exceed CRITICAL_MASS.
+     */
+    async isOverheated() {
+        const contract = getContract({
+            address: this.contractAddress,
+            abi: QUANTUM_TASK_BUFFER_ABI,
+            client: this.publicClient
+        });
+        try {
+            return await contract.read.isOverheated();
+        }
+        catch (error) {
+            console.error("Failed to read isOverheated state from contract:", error);
+            throw new Error("Failed to check thermodynamic state. Assuming overheated for safety.");
+        }
+    }
+    /**
+     * Sleep helper for backoff
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Prepares the `submitTask` transaction call data, enforcing V_AI (Thermodynamic Throttling).
+     * The agent SDK intrinsically checks the `isOverheated` state. If the system is overheated,
+     * the SDK *refuses* to generate the transaction and applies an exponential backoff.
+     *
+     * @param complexityHash The unique hash of the task logic to submit.
+     * @param metadataUri The URI (e.g. ipfs://...) pointing to the standard JSON metadata.
+     * @returns The call data object for use with the Paymaster or standard transaction execution.
+     * @throws OverheatedError if max retries are exceeded while the system remains overheated.
+     */
+    async enforceThrottleAndGetTaskCall(complexityHash, metadataUri) {
+        let attempt = 0;
+        let currentBackoff = this.baseBackoffMs;
+        while (attempt < this.maxRetries) {
+            const overheated = await this.isOverheated();
+            if (!overheated) {
+                // System is safe, generate the transaction call data
+                // Note: the actual submission is usually done via Paymaster/UserOp, 
+                // so we return the raw call data to be appended.
+                // Using generic approach to format call data for viem
+                const { encodeFunctionData } = await import('viem');
+                const encodedData = encodeFunctionData({
+                    abi: QUANTUM_TASK_BUFFER_ABI,
+                    functionName: 'submitTask',
+                    args: [complexityHash, metadataUri]
+                });
+                return {
+                    to: this.contractAddress,
+                    value: 0n,
+                    data: encodedData
+                };
+            }
+            console.warn(`[V_AI Throttling] System is OVERHEATED. Attempt ${attempt + 1}/${this.maxRetries}. Backing off for ${currentBackoff}ms...`);
+            await this.sleep(currentBackoff);
+            // Exponential backoff with jitter
+            attempt++;
+            const jitter = Math.random() * 0.2 + 0.9; // 0.9 - 1.1 multiplier
+            currentBackoff = Math.min(currentBackoff * 2 * jitter, this.maxBackoffMs);
+        }
+        throw new OverheatedError("System critically overheated. Task submission aborted after max retries to preserve macro-economic stability.");
+    }
+}
+//# sourceMappingURL=quantum-client.js.map

package/dist/quantum-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quantum-client.js","sourceRoot":"","sources":["../src/quantum-client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swimmingkiim/api-sdk",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/swimmingkiim/a2a-project.git"

package/src/discovery/attestation-signer.ts

@@ -0,0 +1,171 @@
+import {
+    keccak256,
+    toHex,
+    encodeAbiParameters,
+    isAddress,
+} from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import type { Account } from 'viem'
+import { z } from 'zod'
+
+// --- Validation ---
+const EthAddressSchema = z.string().refine(
+    (val) => isAddress(val),
+    { message: 'Invalid Ethereum address format' }
+)
+
+// --- EIP-712 Type Definitions (must match CredentialVerifier.sol) ---
+const EIP712_DOMAIN = {
+    name: 'CredentialVerifier',
+    version: '1',
+} as const
+
+const ATTESTATION_TYPES = {
+    Attestation: [
+        { name: 'user', type: 'address' },
+        { name: 'didHash', type: 'bytes32' },
+        { name: 'deadline', type: 'uint256' },
+    ],
+} as const
+
+// --- Types ---
+
+/**
+ * Function signature for VC verification.
+ * Injected by the caller — can be trust-sdk's VCHandler or any custom impl.
+ */
+export type VerifyVCFunction = (vcJwt: string) => Promise<{ valid: boolean; did: string }>
+
+export interface AttestationSignerOptions {
+    /** Hex-encoded secp256k1 private key of the voucher (any registered agent or bootstrap) */
+    privateKey: `0x${string}`
+    /** Address of the deployed CredentialVerifier contract */
+    verifierContractAddress: string
+    /** Chain ID (e.g., 8453 for Base Mainnet) */
+    chainId: number
+    /** Injected VC verification function */
+    verifyVC: VerifyVCFunction
+    /** Attestation validity duration in seconds (default: 3600 = 1 hour) */
+    ttlSeconds?: number
+}
+
+/**
+ * Structured attestation proof ready for on-chain submission.
+ */
+export interface AttestationProof {
+    /** keccak256 hash of the verified DID */
+    didHash: `0x${string}`
+    /** Unix timestamp after which the attestation expires */
+    deadline: bigint
+    /** EIP-712 ECDSA signature */
+    signature: string
+    /** Encodes the proof as ABI-packed bytes for contract submission */
+    encode: () => `0x${string}`
+}
+
+const DEFAULT_TTL_SECONDS = 3600 // 1 hour
+
+/**
+ * Creates EIP-712 signed attestation proofs for the on-chain CredentialVerifier.
+ *
+ * Web of Trust: Any registered agent (or bootstrap voucher) can sign attestations
+ * to vouch for new agents. No single trusted signer required.
+ *
+ * @example
+ * ```ts
+ * import { AttestationSigner } from '@swimmingkiim/api-sdk'
+ * import { VCHandler } from '@swimmingkiim/trust-sdk'
+ *
+ * const vcHandler = new VCHandler()
+ * // Any registered agent's key can be used as voucher
+ * const signer = new AttestationSigner({
+ *     privateKey: process.env.VOUCHER_KEY as `0x${string}`,
+ *     verifierContractAddress: '0x...',
+ *     chainId: 8453,
+ *     verifyVC: async (jwt) => {
+ *         const valid = await vcHandler.verifyCredential(jwt)
+ *         const payload = JSON.parse(atob(jwt.split('.')[1]))
+ *         return { valid, did: payload.iss }
+ *     },
+ * })
+ *
+ * const proof = await signer.createAttestation(vcJwt, walletAddress)
+ * // proof.encode() → bytes for AgentRegistry.register(meta, units, proof.encode())
+ * ```
+ */
+export class AttestationSigner {
+    private readonly account: Account
+    private readonly verifierContractAddress: `0x${string}`
+    private readonly chainId: number
+    private readonly verifyVC: VerifyVCFunction
+    private readonly ttlSeconds: number
+
+    constructor(options: AttestationSignerOptions) {
+        EthAddressSchema.parse(options.verifierContractAddress)
+
+        this.account = privateKeyToAccount(options.privateKey)
+        this.verifierContractAddress = options.verifierContractAddress as `0x${string}`
+        this.chainId = options.chainId
+        this.verifyVC = options.verifyVC
+        this.ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS
+    }
+
+    /**
+     * Verifies a VC JWT and produces a signed attestation proof.
+     *
+     * @param vcJwt - Verifiable Credential JWT string
+     * @param walletAddress - The Ethereum address of the agent being attested
+     * @returns AttestationProof with didHash, deadline, signature, and encode()
+     */
+    async createAttestation(vcJwt: string, walletAddress: string): Promise<AttestationProof> {
+        // 1. Validate wallet address
+        EthAddressSchema.parse(walletAddress)
+
+        // 2. Verify VC
+        const { valid, did } = await this.verifyVC(vcJwt)
+        if (!valid) {
+            throw new Error('VC verification failed')
+        }
+
+        // 3. Hash the DID for nullifier
+        const didHash = keccak256(toHex(did)) as `0x${string}`
+
+        // 4. Calculate deadline
+        const deadline = BigInt(Math.floor(Date.now() / 1000) + this.ttlSeconds)
+
+        if (!this.account.signTypedData) {
+            throw new Error('Account does not support signTypedData')
+        }
+
+        // 5. Sign EIP-712 typed data
+        const signature = await this.account.signTypedData({
+            domain: {
+                ...EIP712_DOMAIN,
+                chainId: this.chainId,
+                verifyingContract: this.verifierContractAddress,
+            },
+            types: ATTESTATION_TYPES,
+            primaryType: 'Attestation',
+            message: {
+                user: walletAddress as `0x${string}`,
+                didHash,
+                deadline,
+            },
+        })
+
+        // 6. Return structured proof
+        return {
+            didHash,
+            deadline,
+            signature,
+            encode: () => encodeAbiParameters(
+                [
+                    { name: 'didHash', type: 'bytes32' },
+                    { name: 'deadline', type: 'uint256' },
+                    { name: 'signature', type: 'bytes' },
+                ],
+                [didHash, deadline, signature as `0x${string}`]
+            ),
+        }
+    }
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from './mcp-server.js'
 export * from './discovery/llms-reader.js'
 export * from './discovery/registry-reader.js'
+export * from './discovery/attestation-signer.js'
+export * from './quantum-client.js'
 export * from './types.js'