@sequence0/sdk 0.1.0 → 1.0.1

package/dist/core/client.d.ts

@@ -25,30 +25,86 @@
 import { NetworkConfig, CreateWalletOptions, HealthResponse, StatusResponse, WalletDetail, SignResultResponse } from './types';
 import { Wallet } from '../wallet/wallet';
 import { WsClient } from '../utils/websocket';
+import { UnsignedFeeTx } from '../utils/fee';
 export declare class Sequence0 {
     private config;
     private http;
     private ws;
+    private discovery;
+    private feeManager;
+    private resolvedAgentUrl;
+    private circuitBreaker;
+    /** Map of agent API URL -> timestamp when the agent was marked as failed */
+    private failedAgents;
+    /** Optional signer for wallet ownership proofs */
+    private ownerSigner;
+    /** Owner's Ethereum address (derived from private key when provided) */
+    private ownerAddress;
     /**
      * 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: NetworkConfig);
+    /**
+     * Resolve an agent URL -- uses direct URL if set, otherwise discovers from registry.
+     * Filters out recently-failed agents during discovery.
+     */
+    private getHttp;
+    /**
+     * Select a healthy agent from the registry, filtering out
+     * agents that failed within the last AGENT_EXCLUSION_TTL ms.
+     */
+    private selectAgent;
+    /**
+     * 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.
+     */
+    private failoverToNextAgent;
+    /**
+     * Remove expired entries from the failed agents map.
+     */
+    private pruneExpiredFailures;
+    /**
+     * Create a new HttpClient with the shared circuit breaker and current config.
+     */
+    private createHttpClient;
+    /**
+     * 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).
+     */
+    private withFailover;
     /**
      * 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 }
      * ```
      */
     createWallet(options: CreateWalletOptions): Promise<Wallet>;
@@ -104,6 +160,63 @@ export declare class Sequence0 {
      * Request key refresh for a wallet (proactive security)
      */
     refreshKeys(walletId: string): Promise<void>;
+    /**
+     * Discover active agents from the on-chain registry
+     */
+    discoverAgents(): Promise<import("../utils/discovery").AgentInfo[]>;
+    /**
+     * Discover all active agents from the on-chain registry (paginated).
+     * Fetches all pages when there are more than 100 agents.
+     */
+    discoverAllAgents(): Promise<import("../utils/discovery").AgentInfo[]>;
+    /**
+     * 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`);
+     * ```
+     */
+    getSignatureFee(): Promise<bigint>;
+    /**
+     * 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);
+     * ```
+     */
+    buildFeeTx(walletId: string): Promise<UnsignedFeeTx | null>;
     /**
      * Subscribe to real-time events from the agent network
      *
@@ -115,9 +228,26 @@ export declare class Sequence0 {
      * ```
      */
     subscribe(walletId?: string): Promise<WsClient>;
+    /**
+     * Clean up all resources (HTTP client, rate limiter, WebSocket, circuit breaker).
+     * Call this when you are done using the SDK.
+     */
+    destroy(): void;
     private getWsClient;
     private getRpcUrl;
     private getCurveForChain;
+    /**
+     * 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).
+     */
+    private signOwnershipProof;
     private generateWalletId;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACH,aAAa,EACb,mBAAmB,EAEnB,cAAc,EACd,cAAc,EAEd,YAAY,EAGZ,kBAAkB,EACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,MAAM,EAAgB,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAa,MAAM,oBAAoB,CAAC;AA+BzD,qBAAa,SAAS;IAClB,OAAO,CAAC,MAAM,CAA2D;IACzE,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,EAAE,CAAyB;IAEnC;;;;;;;OAOG;gBACS,MAAM,EAAE,aAAa;IAqBjC;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAiEjE;;;;;;;;;;OAUG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBlD;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAS5C;;;;;;OAMG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ1E;;;;;OAKG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAIxE;;;;;;;OAOG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAiCzF;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC;IAI1C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAIvC;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlD;;;;;;;;;OASG;IACG,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;YAWvC,WAAW;IASzB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,gBAAgB;CAK3B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACH,aAAa,EACb,mBAAmB,EAEnB,cAAc,EACd,cAAc,EAEd,YAAY,EAGZ,kBAAkB,EAErB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,MAAM,EAAgB,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAa,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAAc,aAAa,EAAE,MAAM,cAAc,CAAC;AAgHzD,qBAAa,SAAS;IAClB,OAAO,CAAC,MAAM,CAA2D;IACzE,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,cAAc,CAAwC;IAC9D,4EAA4E;IAC5E,OAAO,CAAC,YAAY,CAAkC;IACtD,kDAAkD;IAClD,OAAO,CAAC,WAAW,CAA4B;IAC/C,wEAAwE;IACxE,OAAO,CAAC,YAAY,CAAuB;IAE3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBACS,MAAM,EAAE,aAAa;IAqEjC;;;OAGG;YACW,OAAO;IAWrB;;;OAGG;YACW,WAAW;IAwBzB;;;;OAIG;YACW,mBAAmB;IA0BjC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;;;OAIG;YACW,YAAY;IAoC1B;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAuFjE;;;;;;;;;;OAUG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BlD;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAY5C;;;;;;OAMG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAyB1E;;;;;OAKG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYxE;;;;;;;OAOG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAqCzF;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC;IAO1C;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAOvC;;OAEG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlD;;OAEG;IACG,cAAc;IAIpB;;;OAGG;IACG,iBAAiB;IAQvB;;;;;;;;;;;;;;;;OAgBG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAKxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAkCjE;;;;;;;;;OASG;IACG,SAAS,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAWrD;;;OAGG;IACH,OAAO,IAAI,IAAI;YAiBD,WAAW;IAUzB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,gBAAgB;IAexB;;;;;;;;;;OAUG;YACW,kBAAkB;IAiChC,OAAO,CAAC,gBAAgB;CAK3B"}