@sequence0/sdk 0.1.0 → 1.0.1

package/dist/core/client.js

@@ -25,14 +25,32 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Sequence0 = void 0;
+const ethers_1 = require("ethers");
 const wallet_1 = require("../wallet/wallet");
 const http_1 = require("../utils/http");
 const websocket_1 = require("../utils/websocket");
+const discovery_1 = require("../utils/discovery");
+const fee_1 = require("../utils/fee");
 const errors_1 = require("../utils/errors");
-/** Default agent node URLs by network */
-const AGENT_URLS = {
-    testnet: 'http://18.220.162.112:8080',
-    mainnet: 'https://api.sequence0.network',
+const validation_1 = require("../utils/validation");
+/** Default agent URL for testnet (we run these ourselves) */
+const TESTNET_AGENT_URL = 'http://3.140.248.117:8080';
+/** HTTP status codes that warrant trying a different agent */
+const FAILOVER_STATUS_CODES = new Set([502, 503, 504]);
+/** Sequence0 chain RPC URLs for on-chain agent discovery */
+const SEQUENCE_RPC = {
+    testnet: 'https://testnet-rpc.sequence0.network',
+    mainnet: 'https://rpc.sequence0.network',
+};
+/** AgentRegistry contract addresses */
+const REGISTRY_ADDRESSES = {
+    testnet: '0xf8d7cc35a22882bb8ac36b9ccadd08e852404377',
+    mainnet: '0x8F642dd318C7A7CD2B295dC4d266C3d2e4838B33',
+};
+/** FeeCollector contract addresses */
+const FEE_COLLECTOR_ADDRESSES = {
+    testnet: '0x0000000000000000000000000000000000000000', // No fee on testnet
+    mainnet: '0x7253ff9f45d1bF8Ed0A23Dfb4E6308adcb1E0eEC',
 };
 /** Default chain RPC URLs */
 const CHAIN_RPCS = {
@@ -44,41 +62,284 @@ const CHAIN_RPCS = {
         bitcoin: 'https://mempool.space/testnet/api',
     },
     mainnet: {
+        // Layer 1s
         ethereum: 'https://eth.llamarpc.com',
         polygon: 'https://polygon-rpc.com',
+        bsc: 'https://bsc-dataseed.binance.org',
+        avalanche: 'https://api.avax.network/ext/bc/C/rpc',
+        fantom: 'https://rpc.ftm.tools',
+        gnosis: 'https://rpc.gnosischain.com',
+        celo: 'https://forno.celo.org',
+        cronos: 'https://evm.cronos.org',
+        moonbeam: 'https://rpc.api.moonbeam.network',
+        moonriver: 'https://rpc.api.moonriver.moonbeam.network',
+        harmony: 'https://api.harmony.one',
+        kava: 'https://evm.kava.io',
+        canto: 'https://canto.slingshot.finance',
+        aurora: 'https://mainnet.aurora.dev',
+        klaytn: 'https://public-en-cypress.klaytn.net',
+        okc: 'https://exchainrpc.okex.org',
+        fuse: 'https://rpc.fuse.io',
+        evmos: 'https://evmos-evm-rpc.publicnode.com',
+        core: 'https://rpc.coredao.org',
+        flare: 'https://flare-api.flare.network/ext/C/rpc',
+        iotex: 'https://babel-api.mainnet.iotex.io',
+        rootstock: 'https://public-node.rsk.co',
+        telos: 'https://mainnet.telos.net/evm',
+        thundercore: 'https://mainnet-rpc.thundercore.com',
+        // Layer 2s
         arbitrum: 'https://arb1.arbitrum.io/rpc',
         optimism: 'https://mainnet.optimism.io',
         base: 'https://mainnet.base.org',
-        bsc: 'https://bsc-dataseed.binance.org',
-        avalanche: 'https://api.avax.network/ext/bc/C/rpc',
+        zksync: 'https://mainnet.era.zksync.io',
+        scroll: 'https://rpc.scroll.io',
+        linea: 'https://rpc.linea.build',
+        mantle: 'https://rpc.mantle.xyz',
+        blast: 'https://rpc.blast.io',
+        mode: 'https://mainnet.mode.network',
+        manta: 'https://pacific-rpc.manta.network/http',
+        'polygon-zkevm': 'https://zkevm-rpc.com',
+        metis: 'https://andromeda.metis.io/?owner=1088',
+        zora: 'https://rpc.zora.energy',
+        sei: 'https://evm-rpc.sei-apis.com',
+        boba: 'https://mainnet.boba.network',
+        taiko: 'https://rpc.mainnet.taiko.xyz',
+        opbnb: 'https://opbnb-mainnet-rpc.bnbchain.org',
+        fraxtal: 'https://rpc.frax.com',
+        worldchain: 'https://worldchain-mainnet.g.alchemy.com/public',
+        lisk: 'https://rpc.api.lisk.com',
+        redstone: 'https://rpc.redstonechain.com',
+        cyber: 'https://cyber.alt.technology',
+        mint: 'https://rpc.mintchain.io',
+        bob: 'https://rpc.gobob.xyz',
+        xai: 'https://xai-chain.net/rpc',
+        morph: 'https://rpc.morphl2.io',
+        'astar-zkevm': 'https://rpc.startale.com/astar-zkevm',
+        // Non-EVM
         solana: 'https://api.mainnet-beta.solana.com',
         bitcoin: 'https://mempool.space/api',
     },
 };
+/** Duration in ms to exclude a failed agent from selection */
+const AGENT_EXCLUSION_TTL = 60000;
 class Sequence0 {
     /**
      * Create a new Sequence0 SDK client
      *
+     * On testnet, connects to the Sequence0-operated agent by default.
+     * On mainnet, auto-discovers agents from the on-chain AgentRegistry.
+     *
      * @example
      * ```typescript
+     * // Mainnet -- auto-discovers agents from on-chain registry
      * const s0 = new Sequence0({ network: 'mainnet' });
+     *
+     * // Or specify a specific agent
+     * const s0 = new Sequence0({ network: 'mainnet', agentUrl: 'http://my-agent:8080' });
+     *
+     * // With debug logging and custom rate limit
+     * const s0 = new Sequence0({
+     *   network: 'mainnet',
+     *   debug: true,
+     *   maxRetries: 5,
+     *   rateLimiter: { maxRequestsPerSecond: 20 },
+     * });
      * ```
      */
     constructor(config) {
+        this.http = null;
         this.ws = null;
+        this.discovery = null;
+        this.feeManager = null;
+        this.resolvedAgentUrl = null;
+        this.circuitBreaker = new http_1.CircuitBreaker();
+        /** Map of agent API URL -> timestamp when the agent was marked as failed */
+        this.failedAgents = new Map();
+        /** Optional signer for wallet ownership proofs */
+        this.ownerSigner = null;
+        /** Owner's Ethereum address (derived from private key when provided) */
+        this.ownerAddress = null;
         const network = config.network || 'mainnet';
-        const agentUrl = config.agentUrl || AGENT_URLS[network] || AGENT_URLS.mainnet;
         this.config = {
             ...config,
             network,
-            agentUrl,
         };
-        this.http = new http_1.HttpClient({
-            baseUrl: agentUrl,
+        // Set up owner signer for ownership proofs on sign requests
+        if (config.ownerSigner) {
+            this.ownerSigner = config.ownerSigner;
+        }
+        else if (config.ownerPrivateKey) {
+            const key = config.ownerPrivateKey.startsWith('0x')
+                ? config.ownerPrivateKey
+                : '0x' + config.ownerPrivateKey;
+            const signingKey = new ethers_1.SigningKey(key);
+            this.ownerAddress = (0, ethers_1.computeAddress)(signingKey.publicKey);
+            this.ownerSigner = async (messageHash) => {
+                const sig = signingKey.sign(messageHash);
+                // Return compact 65-byte signature: r (32) + s (32) + v (1)
+                const v = sig.v === 27 ? '1b' : '1c';
+                return sig.r + sig.s.slice(2) + v;
+            };
+        }
+        const httpOpts = {
             timeout: config.timeout || 30000,
             headers: config.apiKey ? { 'X-API-Key': config.apiKey } : undefined,
+            maxRetries: config.maxRetries,
+            rateLimiter: config.rateLimiter,
+            debug: config.debug,
+            logger: config.logger,
+        };
+        // If agent URL provided directly, use it immediately
+        if (config.agentUrl) {
+            this.resolvedAgentUrl = config.agentUrl;
+            this.http = new http_1.HttpClient({
+                baseUrl: config.agentUrl,
+                circuitBreaker: this.circuitBreaker,
+                ...httpOpts,
+            });
+        }
+        else if (network === 'testnet') {
+            // Testnet: default to our operated agent
+            this.resolvedAgentUrl = TESTNET_AGENT_URL;
+            this.http = new http_1.HttpClient({
+                baseUrl: TESTNET_AGENT_URL,
+                circuitBreaker: this.circuitBreaker,
+                ...httpOpts,
+            });
+        }
+        // Mainnet without agentUrl: lazy discovery on first API call
+        // Always set up discovery for registry queries
+        const seqRpc = config.sequenceRpcUrl || SEQUENCE_RPC[network] || SEQUENCE_RPC.mainnet;
+        const registry = config.registryAddress || REGISTRY_ADDRESSES[network] || REGISTRY_ADDRESSES.mainnet;
+        this.discovery = new discovery_1.AgentDiscovery({ rpcUrl: seqRpc, registryAddress: registry });
+        // Set up FeeManager for fee queries and TX building
+        const feeCollector = config.feeCollectorAddress || FEE_COLLECTOR_ADDRESSES[network] || FEE_COLLECTOR_ADDRESSES.mainnet;
+        if (feeCollector !== '0x0000000000000000000000000000000000000000') {
+            this.feeManager = new fee_1.FeeManager({
+                rpcUrl: seqRpc,
+                feeCollectorAddress: feeCollector,
+                registryAddress: registry,
+            });
+        }
+    }
+    /**
+     * Resolve an agent URL -- uses direct URL if set, otherwise discovers from registry.
+     * Filters out recently-failed agents during discovery.
+     */
+    async getHttp() {
+        if (this.http)
+            return this.http;
+        // Auto-discover agent from on-chain registry, excluding failed agents
+        const agentUrl = await this.selectAgent();
+        this.resolvedAgentUrl = agentUrl;
+        this.http = this.createHttpClient(agentUrl);
+        return this.http;
+    }
+    /**
+     * Select a healthy agent from the registry, filtering out
+     * agents that failed within the last AGENT_EXCLUSION_TTL ms.
+     */
+    async selectAgent() {
+        this.pruneExpiredFailures();
+        const healthy = await this.discovery.getHealthyAgents();
+        const available = healthy.filter((agent) => !this.failedAgents.has(agent.apiUrl));
+        if (available.length === 0) {
+            // If all healthy agents have been excluded, clear exclusions and try again
+            if (healthy.length > 0) {
+                this.failedAgents.clear();
+                const idx = Math.floor(Math.random() * healthy.length);
+                return healthy[idx].apiUrl;
+            }
+            throw new errors_1.NetworkError('No healthy agents found in the registry. The network may not have active node runners yet.');
+        }
+        const idx = Math.floor(Math.random() * available.length);
+        return available[idx].apiUrl;
+    }
+    /**
+     * Mark the current agent as failed and switch to a different one.
+     * Called internally when a request to the current agent fails
+     * after exhausting retries or when the circuit breaker trips.
+     */
+    async failoverToNextAgent() {
+        const failedUrl = this.resolvedAgentUrl;
+        if (failedUrl) {
+            this.failedAgents.set(failedUrl, Date.now());
+        }
+        // Destroy the old HTTP client
+        if (this.http) {
+            this.http.destroy();
+            this.http = null;
+        }
+        // Disconnect WebSocket (bound to old agent)
+        if (this.ws) {
+            this.ws.disconnect();
+            this.ws = null;
+        }
+        // Select a new agent
+        const agentUrl = await this.selectAgent();
+        this.resolvedAgentUrl = agentUrl;
+        this.http = this.createHttpClient(agentUrl);
+        return this.http;
+    }
+    /**
+     * Remove expired entries from the failed agents map.
+     */
+    pruneExpiredFailures() {
+        const now = Date.now();
+        for (const [url, timestamp] of this.failedAgents) {
+            if (now - timestamp >= AGENT_EXCLUSION_TTL) {
+                this.failedAgents.delete(url);
+            }
+        }
+    }
+    /**
+     * Create a new HttpClient with the shared circuit breaker and current config.
+     */
+    createHttpClient(baseUrl) {
+        return new http_1.HttpClient({
+            baseUrl,
+            timeout: this.config.timeout || 30000,
+            headers: this.config.apiKey ? { 'X-API-Key': this.config.apiKey } : undefined,
+            maxRetries: this.config.maxRetries,
+            rateLimiter: this.config.rateLimiter,
+            debug: this.config.debug,
+            logger: this.config.logger,
+            circuitBreaker: this.circuitBreaker,
         });
     }
+    /**
+     * Execute an HTTP request with automatic agent failover.
+     * If the current agent's circuit breaker trips or all retries fail,
+     * tries to failover to a different agent (up to 2 failover attempts).
+     */
+    async withFailover(fn) {
+        const MAX_FAILOVERS = 2;
+        for (let failover = 0; failover <= MAX_FAILOVERS; failover++) {
+            const http = await this.getHttp();
+            try {
+                return await fn(http);
+            }
+            catch (error) {
+                // On circuit breaker error or network error, try failover
+                const isFailoverable = error instanceof http_1.CircuitBreakerError ||
+                    (error instanceof errors_1.NetworkError && FAILOVER_STATUS_CODES.has(error.statusCode ?? 0)) ||
+                    (error instanceof errors_1.NetworkError && !error.statusCode); // connection-level failures
+                if (isFailoverable && failover < MAX_FAILOVERS) {
+                    try {
+                        await this.failoverToNextAgent();
+                        continue;
+                    }
+                    catch {
+                        // If failover itself fails (no agents), throw original error
+                        throw error;
+                    }
+                }
+                throw error;
+            }
+        }
+        // Should be unreachable
+        throw new errors_1.NetworkError('All failover attempts exhausted');
+    }
     // ────────────────────────────────────────────────
     //  Wallet Management
     // ────────────────────────────────────────────────
@@ -86,21 +347,32 @@ class Sequence0 {
      * Create a new threshold wallet via DKG ceremony
      *
      * Initiates Distributed Key Generation with the agent network.
-     * The private key is never assembled — each agent holds a share.
+     * The private key is never assembled -- each agent holds a share.
      *
      * @example
      * ```typescript
      * const wallet = await s0.createWallet({ chain: 'ethereum' });
      * console.log(wallet.address); // 0x...
-     * console.log(wallet.threshold); // { t: 17, n: 24 }
+     * console.log(wallet.threshold); // { t: 16, n: 24 }
      * ```
      */
     async createWallet(options) {
-        const chain = options.chain || 'ethereum';
-        const threshold = options.threshold || { t: 17, n: 24 };
+        // Validate inputs
+        const chain = (0, validation_1.validateChain)(options.chain || 'ethereum');
+        const threshold = options.threshold
+            ? (0, validation_1.validateThreshold)(options.threshold)
+            : { t: 16, n: 24 };
         const curve = options.curve || this.getCurveForChain(chain);
-        const walletId = options.walletId || this.generateWalletId();
+        const walletId = options.walletId
+            ? (0, validation_1.validateWalletId)(options.walletId)
+            : this.generateWalletId();
         const timeout = options.timeout || 60000;
+        const creator = options.creator || this.ownerAddress;
+        // Validate creator address
+        if (!creator || !/^0x[0-9a-fA-F]{40}$/.test(creator)) {
+            throw new errors_1.Sequence0Error('creator must be a valid 0x-prefixed Ethereum address (40 hex chars). ' +
+                'Either pass it in CreateWalletOptions or provide ownerPrivateKey in NetworkConfig.');
+        }
         // Get agent peers to form committee
         const status = await this.getStatus();
         const participants = status.connected_peer_ids.slice(0, threshold.n);
@@ -112,12 +384,16 @@ class Sequence0 {
         // Create a promise that resolves when DKG completes
         const dkgComplete = ws.waitFor('WalletCreated', (e) => e.wallet_id === walletId, timeout);
         // Initiate DKG via REST API
-        const dkgResponse = await this.http.post('/dkg/initiate', {
+        const http = await this.getHttp();
+        const rawDkgResponse = await http.post('/dkg/initiate', {
             wallet_id: walletId,
             participants,
             threshold: threshold.t,
             curve,
+            creator,
         });
+        // Validate the DKG response
+        const dkgResponse = (0, validation_1.validateDkgResponse)(rawDkgResponse, '/dkg/initiate');
         if (dkgResponse.status !== 'initiated') {
             throw new errors_1.DkgError(`DKG initiation failed: ${dkgResponse.status}`);
         }
@@ -125,9 +401,12 @@ class Sequence0 {
         let publicKey;
         try {
             const result = await dkgComplete;
-            publicKey = result.public_key || '';
+            const validated = (0, validation_1.validateDkgCompletion)(result, 'ws:WalletCreated');
+            publicKey = validated.public_key || '';
         }
         catch (e) {
+            if (e instanceof errors_1.DkgError)
+                throw e;
             throw new errors_1.DkgError(`DKG ceremony timed out after ${timeout}ms. The agent network may be busy.`);
         }
         // Derive address from public key based on chain
@@ -138,9 +417,10 @@ class Sequence0 {
             address,
             threshold,
             network: this.config.network,
-            agentUrl: this.config.agentUrl,
+            agentUrl: this.resolvedAgentUrl,
             rpcUrl: this.getRpcUrl(chain),
             curve,
+            ownerSigner: this.ownerSigner || undefined,
         });
     }
     /**
@@ -155,6 +435,8 @@ class Sequence0 {
      * ```
      */
     async getWallet(walletId) {
+        // Validate input
+        (0, validation_1.validateWalletId)(walletId);
         const wallets = await this.listWallets();
         const detail = wallets.find((w) => w.wallet_id === walletId);
         if (!detail) {
@@ -167,17 +449,21 @@ class Sequence0 {
             address: detail.address,
             threshold: { t: detail.threshold, n: detail.size },
             network: this.config.network,
-            agentUrl: this.config.agentUrl,
+            agentUrl: this.resolvedAgentUrl,
             rpcUrl: this.getRpcUrl(chain),
             curve: this.getCurveForChain(chain),
+            ownerSigner: this.ownerSigner || undefined,
         });
     }
     /**
      * List all wallets managed by the agent network
      */
     async listWallets() {
-        const response = await this.http.get('/wallets');
-        return response.wallets;
+        return this.withFailover(async (http) => {
+            const rawResponse = await http.get('/wallets');
+            const response = (0, validation_1.validateWalletsResponse)(rawResponse, '/wallets');
+            return response.wallets;
+        });
     }
     // ────────────────────────────────────────────────
     //  Signing (Low-Level)
@@ -190,11 +476,24 @@ class Sequence0 {
      * @returns request ID for polling
      */
     async requestSignature(walletId, message) {
-        const response = await this.http.post('/sign', {
-            wallet_id: walletId,
-            message,
+        // Validate inputs
+        (0, validation_1.validateWalletId)(walletId);
+        (0, validation_1.validateHexMessage)(message);
+        // Build ownership proof if signer is configured
+        const proof = await this.signOwnershipProof(walletId, message);
+        return this.withFailover(async (http) => {
+            const body = {
+                wallet_id: walletId,
+                message,
+            };
+            if (proof) {
+                body.owner_signature = proof.owner_signature;
+                body.timestamp = proof.timestamp;
+            }
+            const rawResponse = await http.post('/sign', body);
+            const response = (0, validation_1.validateSignResponse)(rawResponse, '/sign');
+            return response.request_id;
         });
-        return response.request_id;
     }
     /**
      * Poll for a signature result
@@ -203,7 +502,14 @@ class Sequence0 {
      * @returns The signature when ready, null if still pending
      */
     async getSignatureResult(requestId) {
-        return this.http.get(`/sign/${requestId}`);
+        if (!requestId || typeof requestId !== 'string') {
+            throw new errors_1.Sequence0Error('requestId must be a non-empty string');
+        }
+        return this.withFailover(async (http) => {
+            const endpoint = `/sign/${requestId}`;
+            const rawResponse = await http.get(endpoint);
+            return (0, validation_1.validateSignResultResponse)(rawResponse, endpoint);
+        });
     }
     /**
      * Request a signature and wait for completion
@@ -214,6 +520,9 @@ class Sequence0 {
      * @returns hex-encoded signature
      */
     async signAndWait(walletId, message, timeoutMs = 30000) {
+        // Validate inputs
+        (0, validation_1.validateWalletId)(walletId);
+        (0, validation_1.validateHexMessage)(message);
         const requestId = await this.requestSignature(walletId, message);
         // Try WebSocket first for real-time notification
         try {
@@ -242,19 +551,116 @@ class Sequence0 {
      * Get agent network status
      */
     async getStatus() {
-        return this.http.get('/status');
+        return this.withFailover(async (http) => {
+            const rawResponse = await http.get('/status');
+            return (0, validation_1.validateStatusResponse)(rawResponse, '/status');
+        });
     }
     /**
      * Health check
      */
     async health() {
-        return this.http.get('/health');
+        return this.withFailover(async (http) => {
+            const rawResponse = await http.get('/health');
+            return (0, validation_1.validateHealthResponse)(rawResponse, '/health');
+        });
     }
     /**
      * Request key refresh for a wallet (proactive security)
      */
     async refreshKeys(walletId) {
-        await this.http.post('/refresh', { wallet_id: walletId });
+        (0, validation_1.validateWalletId)(walletId);
+        return this.withFailover(async (http) => {
+            await http.post('/refresh', { wallet_id: walletId });
+        });
+    }
+    /**
+     * Discover active agents from the on-chain registry
+     */
+    async discoverAgents() {
+        return this.discovery.discoverAgents();
+    }
+    /**
+     * Discover all active agents from the on-chain registry (paginated).
+     * Fetches all pages when there are more than 100 agents.
+     */
+    async discoverAllAgents() {
+        return this.discovery.discoverAllAgents();
+    }
+    // ────────────────────────────────────────────────
+    //  Fees
+    // ────────────────────────────────────────────────
+    /**
+     * Get the current per-signature fee from the FeeCollector contract.
+     *
+     * The fee is paid on the Sequence0 chain (chain ID 800801) in native S0
+     * tokens. 80% goes to the signing agents, 10% to protocol treasury,
+     * 10% to the reserve fund.
+     *
+     * Returns 0n on testnet (no fees).
+     *
+     * @returns Fee in wei as bigint
+     *
+     * @example
+     * ```typescript
+     * const fee = await s0.getSignatureFee();
+     * console.log(`Fee: ${fee} wei`);
+     * ```
+     */
+    async getSignatureFee() {
+        if (!this.feeManager)
+            return 0n;
+        return this.feeManager.getSignatureFee();
+    }
+    /**
+     * Build an unsigned fee-payment transaction for a wallet's signing committee.
+     *
+     * This looks up the wallet's committee from the agent network, resolves
+     * each committee member's Ethereum payment address from the on-chain
+     * AgentRegistry, and builds an unsigned `collectFee()` transaction for
+     * the FeeCollector contract.
+     *
+     * **The app developer must sign and send this transaction themselves** on the
+     * Sequence0 chain (RPC: https://rpc.sequence0.network, chain ID: 800801).
+     * They need S0 native tokens to cover the fee.
+     *
+     * Returns null on testnet (no fees).
+     *
+     * @param walletId - The wallet ID that will be signed with
+     * @returns Unsigned transaction `{ to, data, value }` or null if no fee required
+     *
+     * @example
+     * ```typescript
+     * const feeTx = await s0.buildFeeTx('my-wallet-id');
+     * if (feeTx) {
+     *   // Sign and send with your own wallet on the Sequence0 chain
+     *   const tx = await signer.sendTransaction(feeTx);
+     *   await tx.wait();
+     * }
+     * // Now request the signature
+     * const sig = await s0.signAndWait('my-wallet-id', messageHex);
+     * ```
+     */
+    async buildFeeTx(walletId) {
+        if (!this.feeManager)
+            return null;
+        (0, validation_1.validateWalletId)(walletId);
+        // Fetch wallet details to get the committee peer IDs
+        const wallets = await this.listWallets();
+        const detail = wallets.find((w) => w.wallet_id === walletId);
+        if (!detail) {
+            throw new errors_1.Sequence0Error(`Wallet '${walletId}' not found on ${this.config.network}`);
+        }
+        if (!detail.committee || detail.committee.length === 0) {
+            throw new errors_1.Sequence0Error(`Wallet '${walletId}' has no committee members`);
+        }
+        // Resolve peer IDs to Ethereum payment addresses via the AgentRegistry
+        const agentAddresses = await this.feeManager.resolveAgentPaymentAddresses(detail.committee);
+        if (agentAddresses.length === 0) {
+            throw new errors_1.Sequence0Error(`Could not resolve payment addresses for wallet '${walletId}' committee. ` +
+                'Agents may not be registered on-chain.');
+        }
+        return this.feeManager.buildCollectFeeTx(walletId, agentAddresses);
     }
     // ────────────────────────────────────────────────
     //  WebSocket Events
@@ -270,17 +676,38 @@ class Sequence0 {
      * ```
      */
     async subscribe(walletId) {
-        const wsUrl = this.config.agentUrl.replace(/^http/, 'ws') + '/ws';
+        if (walletId) {
+            (0, validation_1.validateWalletId)(walletId);
+        }
+        await this.getHttp(); // Ensure agent URL is resolved
+        const wsUrl = this.resolvedAgentUrl.replace(/^http/, 'ws') + '/ws';
         const ws = new websocket_1.WsClient({ url: wsUrl, walletId });
         await ws.connect();
         return ws;
     }
+    /**
+     * Clean up all resources (HTTP client, rate limiter, WebSocket, circuit breaker).
+     * Call this when you are done using the SDK.
+     */
+    destroy() {
+        if (this.http) {
+            this.http.destroy();
+            this.http = null;
+        }
+        if (this.ws) {
+            this.ws.disconnect();
+            this.ws = null;
+        }
+        this.circuitBreaker.resetAll();
+        this.failedAgents.clear();
+    }
     // ────────────────────────────────────────────────
     //  Internals
     // ────────────────────────────────────────────────
     async getWsClient() {
         if (!this.ws || !this.ws.connected) {
-            const wsUrl = this.config.agentUrl.replace(/^http/, 'ws') + '/ws';
+            await this.getHttp(); // Ensure agent URL is resolved
+            const wsUrl = this.resolvedAgentUrl.replace(/^http/, 'ws') + '/ws';
             this.ws = new websocket_1.WsClient({ url: wsUrl });
             await this.ws.connect();
         }
@@ -293,11 +720,53 @@ class Sequence0 {
         return networkRpcs[chain] || networkRpcs.ethereum;
     }
     getCurveForChain(chain) {
-        if (chain === 'solana' || chain === 'near' || chain === 'sui' || chain === 'aptos') {
+        // Ed25519 chains — Solana, Near, Sui, Aptos, Polkadot, Cardano, Stellar, TON, Algorand
+        // Note: Cosmos uses secp256k1 by default (same as Ethereum)
+        //       Tezos supports both but secp256k1 is more common
+        //       Polkadot primarily uses sr25519, but ed25519 is supported
+        const ed25519Chains = [
+            'solana', 'near', 'sui', 'aptos', 'polkadot', 'cardano',
+            'stellar', 'ton', 'algorand',
+        ];
+        if (ed25519Chains.includes(chain)) {
             return 'ed25519';
         }
         return 'secp256k1';
     }
+    /**
+     * Build an ownership proof for a sign request.
+     *
+     * The proof is: sign( keccak256( wallet_id_bytes + message_hex_bytes + timestamp_be_bytes ) )
+     *
+     * - wallet_id_bytes: UTF-8 encoding of the wallet ID string
+     * - message_hex_bytes: the raw bytes of the hex-encoded message (i.e. the message as passed to /sign)
+     * - timestamp_be_bytes: 8-byte big-endian encoding of the Unix epoch second
+     *
+     * Returns null when no ownerSigner is configured (backwards compatible).
+     */
+    async signOwnershipProof(walletId, messageHex) {
+        if (!this.ownerSigner)
+            return null;
+        const timestamp = Math.floor(Date.now() / 1000);
+        // wallet_id as UTF-8 bytes
+        const walletIdBytes = new TextEncoder().encode(walletId);
+        // message as UTF-8 string bytes (must match Rust: message.as_bytes())
+        const messageBytes = new TextEncoder().encode(messageHex);
+        // timestamp as 8-byte big-endian
+        const timestampBytes = new Uint8Array(8);
+        const view = new DataView(timestampBytes.buffer);
+        // DataView setBigUint64 writes big-endian by default
+        view.setBigUint64(0, BigInt(timestamp), false);
+        // Concatenate and hash: keccak256(walletId + message + timestamp)
+        const payload = (0, ethers_1.concat)([walletIdBytes, messageBytes, timestampBytes]);
+        const digest = (0, ethers_1.getBytes)((0, ethers_1.keccak256)(payload));
+        // Sign the digest
+        const signature = await this.ownerSigner(digest);
+        return {
+            owner_signature: signature.startsWith('0x') ? signature : '0x' + signature,
+            timestamp,
+        };
+    }
     generateWalletId() {
         const timestamp = Date.now().toString(36);
         const random = Math.random().toString(36).slice(2, 8);