@sequence0/sdk 1.0.0 → 1.0.2

package/dist/core/client.js

@@ -25,13 +25,20 @@
  */
 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");
+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';
+/** Module-level flag to emit HTTP warning only once */
+let _httpWarningEmitted = false;
+/** 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',
@@ -39,8 +46,13 @@ const SEQUENCE_RPC = {
 };
 /** AgentRegistry contract addresses */
 const REGISTRY_ADDRESSES = {
-    testnet: '0xf8d7cc35a22882bb8ac36b9ccadd08e852404377',
-    mainnet: '0xb2c34de56df1041887de1d1103f1a6aa439e4980',
+    testnet: '0xc0437Ae04aA961f90dD237839704155A4E06af5D',
+    mainnet: '0x84E44eD38E30FD1F0ec37D88AbAAE831A90C610E',
+};
+/** FeeCollector contract addresses */
+const FEE_COLLECTOR_ADDRESSES = {
+    testnet: '0x0000000000000000000000000000000000000000', // No fee on testnet
+    mainnet: '0x24963595AdEbf6608Dd20DDBfcEf7D5931a595D9',
 };
 /** Default chain RPC URLs */
 const CHAIN_RPCS = {
@@ -62,10 +74,21 @@ const CHAIN_RPCS = {
         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',
@@ -81,11 +104,26 @@ const CHAIN_RPCS = {
         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
@@ -95,30 +133,70 @@ class Sequence0 {
      *
      * @example
      * ```typescript
-     * // Mainnet — auto-discovers agents from on-chain registry
+     * // 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';
         this.config = {
             ...config,
             network,
         };
+        // 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,
+            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,
-                timeout: config.timeout || 30000,
-                headers: config.apiKey ? { 'X-API-Key': config.apiKey } : undefined,
+                circuitBreaker: this.circuitBreaker,
+                ...httpOpts,
             });
         }
         else if (network === 'testnet') {
@@ -126,31 +204,147 @@ class Sequence0 {
             this.resolvedAgentUrl = TESTNET_AGENT_URL;
             this.http = new http_1.HttpClient({
                 baseUrl: TESTNET_AGENT_URL,
-                timeout: config.timeout || 30000,
-                headers: config.apiKey ? { 'X-API-Key': config.apiKey } : undefined,
+                circuitBreaker: this.circuitBreaker,
+                ...httpOpts,
             });
+            this.warnIfHttp(TESTNET_AGENT_URL);
         }
         // 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 });
+        this.discovery = new discovery_1.AgentDiscovery({
+            rpcUrl: seqRpc,
+            registryAddress: registry,
+            useHttps: config.useHttps,
+        });
+        // 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
+     * 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
-        const agentUrl = await this.discovery.selectAgent();
+        // Auto-discover agent from on-chain registry, excluding failed agents
+        const agentUrl = await this.selectAgent();
+        this.resolvedAgentUrl = agentUrl;
+        this.http = this.createHttpClient(agentUrl);
+        this.warnIfHttp(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 = new http_1.HttpClient({
-            baseUrl: 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,
         });
-        return this.http;
+    }
+    /**
+     * 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
@@ -159,39 +353,71 @@ 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;
-        // Get agent peers to form committee
+        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 (reputation-weighted selection)
         const status = await this.getStatus();
-        const participants = status.connected_peer_ids.slice(0, threshold.n);
-        if (participants.length < threshold.t) {
-            throw new errors_1.DkgError(`Not enough agents: need ${threshold.t}, only ${participants.length} online`);
+        const candidates = status.connected_peer_ids;
+        if (candidates.length < threshold.t) {
+            throw new errors_1.DkgError(`Not enough agents: need ${threshold.t}, only ${candidates.length} online`);
+        }
+        let participants;
+        if (candidates.length <= threshold.n) {
+            // Not enough candidates to be selective — use all
+            participants = candidates;
+        }
+        else {
+            // Fetch reputation scores and select weighted random subset
+            const reputations = await this.discovery.getAgentReputations(candidates);
+            participants = this.weightedRandomSample(candidates, reputations, threshold.n);
         }
         // Connect WebSocket for real-time DKG updates
         const ws = await this.getWsClient();
         // Create a promise that resolves when DKG completes
         const dkgComplete = ws.waitFor('WalletCreated', (e) => e.wallet_id === walletId, timeout);
+        // Generate creator signature proof
+        const creatorProof = await this.signOwnershipProof(walletId, 'dkg');
+        if (!creatorProof) {
+            throw new errors_1.Sequence0Error('ownerSigner or ownerPrivateKey is required to sign DKG requests. ' +
+                'Provide one in NetworkConfig.');
+        }
         // Initiate DKG via REST API
         const http = await this.getHttp();
-        const dkgResponse = await http.post('/dkg/initiate', {
+        const rawDkgResponse = await http.post('/dkg/initiate', {
             wallet_id: walletId,
             participants,
             threshold: threshold.t,
             curve,
+            creator,
+            creator_signature: creatorProof.owner_signature,
+            timestamp: creatorProof.timestamp,
         });
+        // 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}`);
         }
@@ -199,9 +425,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
@@ -215,6 +444,7 @@ class Sequence0 {
             agentUrl: this.resolvedAgentUrl,
             rpcUrl: this.getRpcUrl(chain),
             curve,
+            ownerSigner: this.ownerSigner || undefined,
         });
     }
     /**
@@ -229,6 +459,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) {
@@ -244,15 +476,18 @@ class Sequence0 {
             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 http = await this.getHttp();
-        const response = await 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)
@@ -265,12 +500,24 @@ class Sequence0 {
      * @returns request ID for polling
      */
     async requestSignature(walletId, message) {
-        const http = await this.getHttp();
-        const response = await 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
@@ -279,8 +526,14 @@ class Sequence0 {
      * @returns The signature when ready, null if still pending
      */
     async getSignatureResult(requestId) {
-        const http = await this.getHttp();
-        return 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
@@ -291,6 +544,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 {
@@ -319,22 +575,37 @@ class Sequence0 {
      * Get agent network status
      */
     async getStatus() {
-        const http = await this.getHttp();
-        return 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() {
-        const http = await this.getHttp();
-        return 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)
+     * Request key refresh for a wallet (proactive security).
+     * Requires ownerSigner or ownerPrivateKey in config.
      */
     async refreshKeys(walletId) {
-        const http = await this.getHttp();
-        await http.post('/refresh', { wallet_id: walletId });
+        (0, validation_1.validateWalletId)(walletId);
+        const proof = await this.signOwnershipProof(walletId, 'refresh');
+        if (!proof) {
+            throw new errors_1.Sequence0Error('ownerSigner or ownerPrivateKey is required to sign refresh requests');
+        }
+        return this.withFailover(async (http) => {
+            await http.post('/refresh', {
+                wallet_id: walletId,
+                owner_signature: proof.owner_signature,
+                timestamp: proof.timestamp,
+            });
+        });
     }
     /**
      * Discover active agents from the on-chain registry
@@ -342,6 +613,88 @@ class Sequence0 {
     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
     // ────────────────────────────────────────────────
@@ -356,12 +709,31 @@ class Sequence0 {
      * ```
      */
     async subscribe(walletId) {
+        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
     // ────────────────────────────────────────────────
@@ -381,12 +753,93 @@ class Sequence0 {
         return networkRpcs[chain] || networkRpcs.ethereum;
     }
     getCurveForChain(chain) {
-        const ed25519Chains = ['solana', 'near', 'sui', 'aptos', 'cosmos', 'polkadot', 'cardano'];
+        // 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,
+        };
+    }
+    /**
+     * Weighted random sampling without replacement.
+     * Agents with higher reputation scores are more likely to be selected.
+     * All agents have a minimum weight of 1 so new agents still have a chance.
+     */
+    weightedRandomSample(candidates, reputations, n) {
+        // Build weighted list: weight = max(reputation, 1)
+        const weighted = candidates.map((id) => ({
+            id,
+            weight: Math.max(reputations.get(id) ?? 0, 1),
+        }));
+        const selected = [];
+        const remaining = [...weighted];
+        for (let i = 0; i < n && remaining.length > 0; i++) {
+            const totalWeight = remaining.reduce((sum, w) => sum + w.weight, 0);
+            let rand = Math.random() * totalWeight;
+            let picked = remaining.length - 1; // fallback to last
+            for (let j = 0; j < remaining.length; j++) {
+                rand -= remaining[j].weight;
+                if (rand <= 0) {
+                    picked = j;
+                    break;
+                }
+            }
+            selected.push(remaining[picked].id);
+            remaining.splice(picked, 1);
+        }
+        return selected;
+    }
+    /**
+     * Emit a one-time warning if the agent URL uses plain HTTP.
+     */
+    warnIfHttp(url) {
+        if (!_httpWarningEmitted && url.startsWith('http://')) {
+            _httpWarningEmitted = true;
+            console.warn('[Sequence0] Connecting to agent via HTTP (unencrypted). ' +
+                'Use HTTPS in production to protect signing requests and ownership proofs. ' +
+                'Set useHttps: true in config for discovered agents, or provide an https:// agentUrl.');
+        }
+    }
     generateWalletId() {
         const timestamp = Date.now().toString(36);
         const random = Math.random().toString(36).slice(2, 8);