signet.js 0.2.0 → 0.3.1-beta.1

package/dist/index.d.cts

@@ -158,7 +158,7 @@ declare const najToUncompressedPubKeySEC1: (najPublicKey: NajPublicKey) => Uncom
  * @param keyVersion - Key version controlling which derivation prefix to use (legacy v1 for 0, CAIP-2 v2 otherwise)
  * @returns The derived child public key in uncompressed SEC1 format (04 || x || y)
  */
-declare function deriveChildPublicKey(rootUncompressedPubKeySEC1: UncompressedPubKeySEC1, predecessorId: string, path: string | undefined, chainId: string, keyVersion: number): UncompressedPubKeySEC1;
+declare function deriveChildPublicKey(rootUncompressedPubKeySEC1: UncompressedPubKeySEC1, predecessorId: string, path: string | undefined, chainId: string, _keyVersion: number): UncompressedPubKeySEC1;
 /**
  * Verifies that a secp256k1 signature was created by the expected derived address
  * by recovering the signing address and comparing it with the address derived from the contract.
@@ -771,6 +771,16 @@ interface SignatureErrorData {
   requestId: string;
   error: string;
 }
+interface RequestIdArgs {
+  address: Address;
+  payload: Hex;
+  path: string;
+  keyVersion: number;
+  chainId: bigint;
+  algo: string;
+  dest: string;
+  params: string;
+}
 //#endregion
 //#region src/contracts/evm/ChainSignaturesContract.d.ts
 /**
@@ -882,8 +892,43 @@ declare class ChainSignatureContract$2 extends ChainSignatureContract {
    */
   getSignatureFromEvents(requestId: Hex, fromBlock: bigint): Promise<RSVSignature | undefined>;
 }
+//#endregion
+//#region src/contracts/evm/utils.d.ts
+/**
+ * Generates a unique request ID for EVM signature requests using keccak256 hashing.
+ *
+ * The request ID is computed by ABI-encoding the request parameters and hashing
+ * the result. This ID is used to track signature requests and match them with
+ * responses from the MPC network.
+ *
+ * @param request - The signature request parameters
+ * @param request.address - The address of the requester (EVM address format)
+ * @param request.payload - The data payload to be signed as a hex string
+ * @param request.path - The derivation path for the signing key
+ * @param request.keyVersion - The version of the signing key
+ * @param request.chainId - The chain ID where the request originated
+ * @param request.algo - The signing algorithm identifier
+ * @param request.dest - The destination identifier for the signature
+ * @param request.params - Additional parameters for the signing process
+ * @returns The keccak256 hash of the encoded request as a hex string
+ *
+ * @example
+ * ```typescript
+ * const requestId = getRequestIdRespond({
+ *   address: '0x1234...abcd',
+ *   payload: '0xdeadbeef',
+ *   path: 'ethereum,1',
+ *   keyVersion: 0,
+ *   chainId: 1n,
+ *   algo: '',
+ *   dest: '',
+ *   params: '',
+ * })
+ * ```
+ */
+declare const getRequestIdRespond$1: (request: RequestIdArgs) => `0x${string}`;
 declare namespace index_d_exports$3 {
-  export { ChainSignatureContract$2 as ChainSignatureContract, utils$1 as utils };
+  export { ChainSignatureContract$2 as ChainSignatureContract, RequestIdArgs, getRequestIdRespond$1 as getRequestIdRespond, utils$1 as utils };
 }
 declare const utils$1: {
   ChainSignaturesContractABI: typeof ChainSignaturesContractABI_d_exports;
@@ -1550,16 +1595,17 @@ interface Signature {
   s: number[];
   recoveryId: number;
 }
-interface SignatureRespondedEvent {
-  requestId: number[];
-  responder: PublicKey;
+interface RespondBidirectionalData {
+  serializedOutput: Buffer;
   signature: Signature;
 }
-interface SignatureErrorEvent {
-  requestId: number[];
-  responder: PublicKey;
-  error: string;
+type ChainSignaturesEventName = 'signatureRespondedEvent' | 'signatureErrorEvent' | 'respondBidirectionalEvent';
+interface EventResultMap {
+  signatureRespondedEvent: RSVSignature;
+  signatureErrorEvent: SignatureErrorData;
+  respondBidirectionalEvent: RespondBidirectionalData;
 }
+type EventResult<E extends ChainSignaturesEventName> = EventResultMap[E];
 //#endregion
 //#region src/contracts/solana/ChainSignaturesContract.d.ts
 declare class ChainSignatureContract$1 extends ChainSignatureContract {
@@ -1608,8 +1654,8 @@ declare class ChainSignatureContract$1 extends ChainSignatureContract {
   }): Promise<TransactionInstruction>;
   /**
    * Sends a transaction to the program to request a signature, then
-   * polls for the signature result. If the signature is not found within the retry
-   * parameters, it will throw an error.
+   * races a WebSocket listener against polling backfill to find the result.
+   * If the signature is not found within the timeout, it will throw an error.
    */
   sign(args: SignArgs, options?: Partial<SignOptions> & {
     remainingAccounts?: AccountMeta[];
@@ -1617,42 +1663,118 @@ declare class ChainSignatureContract$1 extends ChainSignatureContract {
   }): Promise<RSVSignature>;
   private sendAndConfirmWithoutWebSocket;
   /**
-   * Polls for signature or error events matching the given requestId starting from the solana transaction with signature afterSignature.
-   * Returns a signature, error data, or undefined if nothing is found.
+   * Waits for a specific event matching the given requestId by combining
+   * a WebSocket listener (real-time) with polling backfill (resilience).
    */
-  pollForRequestId({
-    requestId,
-    payload: _payload,
-    path: _path,
-    afterSignature,
-    options
-  }: {
+  waitForEvent<E extends ChainSignaturesEventName>(options: {
+    eventName: E;
     requestId: string;
-    payload: number[];
-    path: string;
-    afterSignature: string;
-    options?: RetryOptions;
-  }): Promise<RSVSignature | SignatureErrorData | undefined>;
-  /**
-   * Parses transaction logs for signature or error events.
-   */
-  private parseLogsForEvents;
-  private mapEventToResult;
+    signer: PublicKey;
+    afterSignature?: string;
+    timeoutMs?: number;
+    backfillIntervalMs?: number;
+    backfillLimit?: number;
+    signal?: AbortSignal;
+  }): Promise<EventResult<E>>;
+  private mapRespondToResult;
+  private mapRespondErrorToResult;
+  private mapRespondBidirectionalToResult;
+  private mapEventForName;
   /**
    * Generates the request ID for a signature request allowing to track the response.
    */
   getRequestId(args: SignArgs, options?: SignOptions['sign']): string;
-  /**
-   * Subscribes to program events using Anchor's EventParser for regular events,
-   * and CPI parsing for emit_cpi!-emitted events. Returns an unsubscribe fn.
-   */
-  subscribeToEvents(handlers: {
-    onSignatureResponded?: (event: SignatureRespondedEvent, slot: number) => Promise<void> | void;
-    onSignatureError?: (event: SignatureErrorEvent, slot: number) => Promise<void> | void;
-  }): Promise<() => Promise<void>>;
 }
+//#endregion
+//#region src/contracts/solana/utils.d.ts
+interface SolanaRequestIdArgs {
+  address: string;
+  payload: Uint8Array | number[];
+  path: string;
+  keyVersion: number;
+  chainId: string;
+  algo: string;
+  dest: string;
+  params: string;
+}
+interface SolanaBidirectionalRequestIdArgs {
+  sender: string;
+  payload: Uint8Array | number[];
+  caip2Id: string;
+  keyVersion: number;
+  path: string;
+  algo: string;
+  dest: string;
+  params: string;
+}
+/**
+ * Generates a unique request ID for Solana signature requests using keccak256 hashing.
+ *
+ * The request ID is computed by ABI-encoding the request parameters and hashing
+ * the result. This ID is used to track signature requests and match them with
+ * responses from the MPC network.
+ *
+ * @param request - The signature request parameters
+ * @param request.address - The sender's address (Solana public key as string)
+ * @param request.payload - The data payload to be signed
+ * @param request.path - The derivation path for the signing key
+ * @param request.keyVersion - The version of the signing key
+ * @param request.chainId - The CAIP-2 chain identifier (e.g., 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')
+ * @param request.algo - The signing algorithm identifier
+ * @param request.dest - The destination identifier for the signature
+ * @param request.params - Additional parameters for the signing process
+ * @returns The keccak256 hash of the encoded request as a hex string
+ *
+ * @example
+ * ```typescript
+ * const requestId = getRequestIdRespond({
+ *   address: 'So11111111111111111111111111111111111111112',
+ *   payload: new Uint8Array([1, 2, 3, 4]),
+ *   path: 'solana,1',
+ *   keyVersion: 0,
+ *   chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+ *   algo: '',
+ *   dest: '',
+ *   params: '',
+ * })
+ * ```
+ */
+declare function getRequestIdRespond(request: SolanaRequestIdArgs): string;
+/**
+ * Generates a unique request ID for bidirectional sign operations using keccak256 hashing.
+ *
+ * Unlike `getRequestIdRespond`, this function uses packed encoding (solidityPacked)
+ * instead of standard ABI encoding. This is used for cross-chain bidirectional
+ * signing flows where the request originates from a different chain.
+ *
+ * @param request - The bidirectional signature request parameters
+ * @param request.sender - The sender's address (Solana public key as string)
+ * @param request.payload - The data payload to be signed
+ * @param request.caip2Id - The CAIP-2 chain identifier (e.g., 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')
+ * @param request.keyVersion - The version of the signing key
+ * @param request.path - The derivation path for the signing key
+ * @param request.algo - The signing algorithm identifier
+ * @param request.dest - The destination identifier for the signature
+ * @param request.params - Additional parameters for the signing process
+ * @returns The keccak256 hash of the packed encoded request as a hex string
+ *
+ * @example
+ * ```typescript
+ * const requestId = getRequestIdBidirectional({
+ *   sender: 'So11111111111111111111111111111111111111112',
+ *   payload: new Uint8Array([1, 2, 3, 4]),
+ *   caip2Id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+ *   keyVersion: 0,
+ *   path: 'ethereum,1',
+ *   algo: '',
+ *   dest: '',
+ *   params: '',
+ * })
+ * ```
+ */
+declare function getRequestIdBidirectional(request: SolanaBidirectionalRequestIdArgs): string;
 declare namespace index_d_exports$4 {
-  export { ChainSignatureContract$1 as ChainSignatureContract, ChainSignaturesProject, utils };
+  export { ChainSignatureContract$1 as ChainSignatureContract, ChainSignaturesProject, SolanaBidirectionalRequestIdArgs, SolanaRequestIdArgs, getRequestIdBidirectional, getRequestIdRespond, utils };
 }
 declare const utils: {
   ChainSignaturesContractIdl: {

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import * as bitcoin from "bitcoinjs-lib";
 import { EncodeObject } from "@cosmjs/proto-signing";
 import { TxRaw } from "cosmjs-types/cosmos/tx/v1beta1/tx.js";
 import BN from "bn.js";
+import "viem/chains";
 import { AnchorProvider, Idl } from "@coral-xyz/anchor";
 import { AccountMeta, Connection, PublicKey, Signer, TransactionInstruction } from "@solana/web3.js";
 
@@ -156,7 +157,7 @@ declare const najToUncompressedPubKeySEC1: (najPublicKey: NajPublicKey) => Uncom
  * @param keyVersion - Key version controlling which derivation prefix to use (legacy v1 for 0, CAIP-2 v2 otherwise)
  * @returns The derived child public key in uncompressed SEC1 format (04 || x || y)
  */
-declare function deriveChildPublicKey(rootUncompressedPubKeySEC1: UncompressedPubKeySEC1, predecessorId: string, path: string | undefined, chainId: string, keyVersion: number): UncompressedPubKeySEC1;
+declare function deriveChildPublicKey(rootUncompressedPubKeySEC1: UncompressedPubKeySEC1, predecessorId: string, path: string | undefined, chainId: string, _keyVersion: number): UncompressedPubKeySEC1;
 /**
  * Verifies that a secp256k1 signature was created by the expected derived address
  * by recovering the signing address and comparing it with the address derived from the contract.
@@ -769,6 +770,16 @@ interface SignatureErrorData {
   requestId: string;
   error: string;
 }
+interface RequestIdArgs {
+  address: Address;
+  payload: Hex;
+  path: string;
+  keyVersion: number;
+  chainId: bigint;
+  algo: string;
+  dest: string;
+  params: string;
+}
 //#endregion
 //#region src/contracts/evm/ChainSignaturesContract.d.ts
 /**
@@ -880,8 +891,43 @@ declare class ChainSignatureContract$2 extends ChainSignatureContract {
    */
   getSignatureFromEvents(requestId: Hex, fromBlock: bigint): Promise<RSVSignature | undefined>;
 }
+//#endregion
+//#region src/contracts/evm/utils.d.ts
+/**
+ * Generates a unique request ID for EVM signature requests using keccak256 hashing.
+ *
+ * The request ID is computed by ABI-encoding the request parameters and hashing
+ * the result. This ID is used to track signature requests and match them with
+ * responses from the MPC network.
+ *
+ * @param request - The signature request parameters
+ * @param request.address - The address of the requester (EVM address format)
+ * @param request.payload - The data payload to be signed as a hex string
+ * @param request.path - The derivation path for the signing key
+ * @param request.keyVersion - The version of the signing key
+ * @param request.chainId - The chain ID where the request originated
+ * @param request.algo - The signing algorithm identifier
+ * @param request.dest - The destination identifier for the signature
+ * @param request.params - Additional parameters for the signing process
+ * @returns The keccak256 hash of the encoded request as a hex string
+ *
+ * @example
+ * ```typescript
+ * const requestId = getRequestIdRespond({
+ *   address: '0x1234...abcd',
+ *   payload: '0xdeadbeef',
+ *   path: 'ethereum,1',
+ *   keyVersion: 0,
+ *   chainId: 1n,
+ *   algo: '',
+ *   dest: '',
+ *   params: '',
+ * })
+ * ```
+ */
+declare const getRequestIdRespond$1: (request: RequestIdArgs) => `0x${string}`;
 declare namespace index_d_exports$3 {
-  export { ChainSignatureContract$2 as ChainSignatureContract, utils$1 as utils };
+  export { ChainSignatureContract$2 as ChainSignatureContract, RequestIdArgs, getRequestIdRespond$1 as getRequestIdRespond, utils$1 as utils };
 }
 declare const utils$1: {
   ChainSignaturesContractABI: typeof ChainSignaturesContractABI_d_exports;
@@ -1548,16 +1594,17 @@ interface Signature {
   s: number[];
   recoveryId: number;
 }
-interface SignatureRespondedEvent {
-  requestId: number[];
-  responder: PublicKey;
+interface RespondBidirectionalData {
+  serializedOutput: Buffer;
   signature: Signature;
 }
-interface SignatureErrorEvent {
-  requestId: number[];
-  responder: PublicKey;
-  error: string;
+type ChainSignaturesEventName = 'signatureRespondedEvent' | 'signatureErrorEvent' | 'respondBidirectionalEvent';
+interface EventResultMap {
+  signatureRespondedEvent: RSVSignature;
+  signatureErrorEvent: SignatureErrorData;
+  respondBidirectionalEvent: RespondBidirectionalData;
 }
+type EventResult<E extends ChainSignaturesEventName> = EventResultMap[E];
 //#endregion
 //#region src/contracts/solana/ChainSignaturesContract.d.ts
 declare class ChainSignatureContract$1 extends ChainSignatureContract {
@@ -1606,8 +1653,8 @@ declare class ChainSignatureContract$1 extends ChainSignatureContract {
   }): Promise<TransactionInstruction>;
   /**
    * Sends a transaction to the program to request a signature, then
-   * polls for the signature result. If the signature is not found within the retry
-   * parameters, it will throw an error.
+   * races a WebSocket listener against polling backfill to find the result.
+   * If the signature is not found within the timeout, it will throw an error.
    */
   sign(args: SignArgs, options?: Partial<SignOptions> & {
     remainingAccounts?: AccountMeta[];
@@ -1615,42 +1662,118 @@ declare class ChainSignatureContract$1 extends ChainSignatureContract {
   }): Promise<RSVSignature>;
   private sendAndConfirmWithoutWebSocket;
   /**
-   * Polls for signature or error events matching the given requestId starting from the solana transaction with signature afterSignature.
-   * Returns a signature, error data, or undefined if nothing is found.
+   * Waits for a specific event matching the given requestId by combining
+   * a WebSocket listener (real-time) with polling backfill (resilience).
    */
-  pollForRequestId({
-    requestId,
-    payload: _payload,
-    path: _path,
-    afterSignature,
-    options
-  }: {
+  waitForEvent<E extends ChainSignaturesEventName>(options: {
+    eventName: E;
     requestId: string;
-    payload: number[];
-    path: string;
-    afterSignature: string;
-    options?: RetryOptions;
-  }): Promise<RSVSignature | SignatureErrorData | undefined>;
-  /**
-   * Parses transaction logs for signature or error events.
-   */
-  private parseLogsForEvents;
-  private mapEventToResult;
+    signer: PublicKey;
+    afterSignature?: string;
+    timeoutMs?: number;
+    backfillIntervalMs?: number;
+    backfillLimit?: number;
+    signal?: AbortSignal;
+  }): Promise<EventResult<E>>;
+  private mapRespondToResult;
+  private mapRespondErrorToResult;
+  private mapRespondBidirectionalToResult;
+  private mapEventForName;
   /**
    * Generates the request ID for a signature request allowing to track the response.
    */
   getRequestId(args: SignArgs, options?: SignOptions['sign']): string;
-  /**
-   * Subscribes to program events using Anchor's EventParser for regular events,
-   * and CPI parsing for emit_cpi!-emitted events. Returns an unsubscribe fn.
-   */
-  subscribeToEvents(handlers: {
-    onSignatureResponded?: (event: SignatureRespondedEvent, slot: number) => Promise<void> | void;
-    onSignatureError?: (event: SignatureErrorEvent, slot: number) => Promise<void> | void;
-  }): Promise<() => Promise<void>>;
 }
+//#endregion
+//#region src/contracts/solana/utils.d.ts
+interface SolanaRequestIdArgs {
+  address: string;
+  payload: Uint8Array | number[];
+  path: string;
+  keyVersion: number;
+  chainId: string;
+  algo: string;
+  dest: string;
+  params: string;
+}
+interface SolanaBidirectionalRequestIdArgs {
+  sender: string;
+  payload: Uint8Array | number[];
+  caip2Id: string;
+  keyVersion: number;
+  path: string;
+  algo: string;
+  dest: string;
+  params: string;
+}
+/**
+ * Generates a unique request ID for Solana signature requests using keccak256 hashing.
+ *
+ * The request ID is computed by ABI-encoding the request parameters and hashing
+ * the result. This ID is used to track signature requests and match them with
+ * responses from the MPC network.
+ *
+ * @param request - The signature request parameters
+ * @param request.address - The sender's address (Solana public key as string)
+ * @param request.payload - The data payload to be signed
+ * @param request.path - The derivation path for the signing key
+ * @param request.keyVersion - The version of the signing key
+ * @param request.chainId - The CAIP-2 chain identifier (e.g., 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')
+ * @param request.algo - The signing algorithm identifier
+ * @param request.dest - The destination identifier for the signature
+ * @param request.params - Additional parameters for the signing process
+ * @returns The keccak256 hash of the encoded request as a hex string
+ *
+ * @example
+ * ```typescript
+ * const requestId = getRequestIdRespond({
+ *   address: 'So11111111111111111111111111111111111111112',
+ *   payload: new Uint8Array([1, 2, 3, 4]),
+ *   path: 'solana,1',
+ *   keyVersion: 0,
+ *   chainId: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+ *   algo: '',
+ *   dest: '',
+ *   params: '',
+ * })
+ * ```
+ */
+declare function getRequestIdRespond(request: SolanaRequestIdArgs): string;
+/**
+ * Generates a unique request ID for bidirectional sign operations using keccak256 hashing.
+ *
+ * Unlike `getRequestIdRespond`, this function uses packed encoding (solidityPacked)
+ * instead of standard ABI encoding. This is used for cross-chain bidirectional
+ * signing flows where the request originates from a different chain.
+ *
+ * @param request - The bidirectional signature request parameters
+ * @param request.sender - The sender's address (Solana public key as string)
+ * @param request.payload - The data payload to be signed
+ * @param request.caip2Id - The CAIP-2 chain identifier (e.g., 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')
+ * @param request.keyVersion - The version of the signing key
+ * @param request.path - The derivation path for the signing key
+ * @param request.algo - The signing algorithm identifier
+ * @param request.dest - The destination identifier for the signature
+ * @param request.params - Additional parameters for the signing process
+ * @returns The keccak256 hash of the packed encoded request as a hex string
+ *
+ * @example
+ * ```typescript
+ * const requestId = getRequestIdBidirectional({
+ *   sender: 'So11111111111111111111111111111111111111112',
+ *   payload: new Uint8Array([1, 2, 3, 4]),
+ *   caip2Id: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+ *   keyVersion: 0,
+ *   path: 'ethereum,1',
+ *   algo: '',
+ *   dest: '',
+ *   params: '',
+ * })
+ * ```
+ */
+declare function getRequestIdBidirectional(request: SolanaBidirectionalRequestIdArgs): string;
 declare namespace index_d_exports$4 {
-  export { ChainSignatureContract$1 as ChainSignatureContract, ChainSignaturesProject, utils };
+  export { ChainSignatureContract$1 as ChainSignatureContract, ChainSignaturesProject, SolanaBidirectionalRequestIdArgs, SolanaRequestIdArgs, getRequestIdBidirectional, getRequestIdRespond, utils };
 }
 declare const utils: {
   ChainSignaturesContractIdl: {