@verbeth/sdk 0.1.4 → 0.1.6

package/dist/esm/src/verify.js

@@ -1,13 +1,14 @@
 // packages/sdk/src/verify.ts
 import { getBytes, hexlify, getAddress } from "ethers";
-import { decryptAndExtractHandshakeKeys, computeTagFromInitiator, verifyDuplexTopicsChecksum, deriveDuplexTopics } from "./crypto.js";
+import { decryptAndExtractHandshakeKeys, computeHybridTagFromInitiator } from "./crypto.js";
+import { kem } from "./pq/kem.js";
 import { parseHandshakePayload, parseHandshakeKeys } from "./payload.js";
 import { makeViemPublicClient, parseBindingMessage, } from "./utils.js";
 // ============= Handshake Verification =============
 /**
  * handshake verification with mandatory identity proof
  */
-export async function verifyHandshakeIdentity(handshakeEvent, provider) {
+export async function verifyHandshakeIdentity(handshakeEvent, provider, ctx) {
     try {
         let plaintextPayload = handshakeEvent.plaintextPayload;
         if (typeof plaintextPayload === "string" &&
@@ -27,13 +28,7 @@ export async function verifyHandshakeIdentity(handshakeEvent, provider) {
             console.error("Failed to parse unified pubKeys from handshake event");
             return false;
         }
-        // // 6492 awareness
-        // const dp: any = content.identityProof;
-        // const sigPrimary: string = dp.signature;
-        // const sig6492: string | undefined = dp.signature6492 ?? dp.erc6492;
-        // const uses6492 = hasERC6492Suffix(sigPrimary) || !!sig6492;
-        // const isContract1271 = await isSmartContract1271(handshakeEvent.sender, provider);
-        return await verifyIdentityProof(content.identityProof, handshakeEvent.sender, parsedKeys, provider);
+        return await verifyIdentityProof(content.identityProof, handshakeEvent.sender, parsedKeys, provider, ctx);
     }
     catch (err) {
         console.error("verifyHandshakeIdentity error:", err);
@@ -44,7 +39,7 @@ export async function verifyHandshakeIdentity(handshakeEvent, provider) {
 /**
  * handshake response verification with mandatory identity proof
  */
-export async function verifyHandshakeResponseIdentity(responseEvent, responderIdentityPubKey, initiatorEphemeralSecretKey, provider) {
+export async function verifyHandshakeResponseIdentity(responseEvent, responderIdentityPubKey, initiatorEphemeralSecretKey, provider, ctx) {
     try {
         const extractedResponse = decryptAndExtractHandshakeKeys(responseEvent.ciphertext, initiatorEphemeralSecretKey);
         if (!extractedResponse) {
@@ -55,21 +50,16 @@ export async function verifyHandshakeResponseIdentity(responseEvent, responderId
             console.error("Identity public key mismatch in handshake response");
             return false;
         }
-        // 6492 awareness
         const dpAny = extractedResponse.identityProof;
         if (!dpAny) {
             console.error("Missing identityProof in handshake response payload");
             return false;
         }
-        // const sigPrimary: string = dpAny.signature;
-        // const sig6492: string | undefined = dpAny.signature6492 ?? dpAny.erc6492;
-        // const uses6492 = hasERC6492Suffix(sigPrimary) || !!sig6492;
-        // const isContract1271 = await isSmartContract1271(responseEvent.responder,provider);
         const expectedKeys = {
             identityPubKey: extractedResponse.identityPubKey,
             signingPubKey: extractedResponse.signingPubKey,
         };
-        return await verifyIdentityProof(extractedResponse.identityProof, responseEvent.responder, expectedKeys, provider);
+        return await verifyIdentityProof(extractedResponse.identityProof, responseEvent.responder, expectedKeys, provider, ctx);
     }
     catch (err) {
         console.error("verifyHandshakeResponseIdentity error:", err);
@@ -77,31 +67,36 @@ export async function verifyHandshakeResponseIdentity(responseEvent, responderId
     }
 }
 /**
- * Verify "IdentityProof" for EOAs and smart accounts.
+ * Verify IdentityProof for EOAs and smart accounts.
  * - Verifies the signature with viem (EOA / ERC-1271 / ERC-6492).
  * - Parses and checks the expected address and public key against the message content.
  */
-export async function verifyIdentityProof(identityProof, smartAccountAddress, expectedUnifiedKeys, provider) {
+export async function verifyIdentityProof(identityProof, address, expectedUnifiedKeys, provider, ctx) {
     try {
         const client = await makeViemPublicClient(provider);
-        const address = smartAccountAddress;
+        const inputAddress = address;
+        const parsed = parseBindingMessage(identityProof.message);
+        if (!parsed.address) {
+            console.error("Parsed address is undefined");
+            return false;
+        }
+        const signerAddress = getAddress(parsed.address);
         const okSig = await client.verifyMessage({
-            address,
+            address: signerAddress,
             message: identityProof.message,
             signature: identityProof.signature,
         });
         if (!okSig) {
-            console.error("Binding signature invalid for address");
+            console.error("Binding signature invalid for signer address");
             return false;
         }
-        const parsed = parseBindingMessage(identityProof.message);
         if (parsed.header && parsed.header !== "VerbEth Key Binding v1") {
             console.error("Unexpected binding header:", parsed.header);
             return false;
         }
-        if (!parsed.address ||
-            getAddress(parsed.address) !== getAddress(smartAccountAddress)) {
-            console.error("Binding message address mismatch");
+        if (!parsed.executorSafeAddress ||
+            getAddress(parsed.executorSafeAddress) !== getAddress(inputAddress)) {
+            console.error("Binding message Safe address mismatch");
             return false;
         }
         const expectedPkX = hexlify(expectedUnifiedKeys.identityPubKey);
@@ -122,7 +117,19 @@ export async function verifyIdentityProof(identityProof, smartAccountAddress, ex
             console.error("Unexpected version:", parsed.version);
             return false;
         }
-        // if (typeof parsed.chainId === 'number' && parsed.chainId !== currentChainId) return false;
+        // anti replay cross chain or cross dapp:
+        if (typeof ctx?.chainId === "number") {
+            if (typeof parsed.chainId !== "number" || parsed.chainId !== ctx.chainId) {
+                console.error("ChainId mismatch");
+                return false;
+            }
+        }
+        if (ctx?.rpId) {
+            if (!parsed.rpId || parsed.rpId !== ctx.rpId) {
+                console.error("RpId mismatch");
+                return false;
+            }
+        }
         return true;
     }
     catch (err) {
@@ -131,8 +138,8 @@ export async function verifyIdentityProof(identityProof, smartAccountAddress, ex
     }
 }
 // ============= Utility Functions =============
-export async function verifyAndExtractHandshakeKeys(handshakeEvent, provider) {
-    const isValid = await verifyHandshakeIdentity(handshakeEvent, provider);
+export async function verifyAndExtractHandshakeKeys(handshakeEvent, provider, ctx) {
+    const isValid = await verifyHandshakeIdentity(handshakeEvent, provider, ctx);
     if (!isValid) {
         return { isValid: false };
     }
@@ -145,17 +152,23 @@ export async function verifyAndExtractHandshakeKeys(handshakeEvent, provider) {
         keys: parsedKeys,
     };
 }
-export async function verifyAndExtractHandshakeResponseKeys(responseEvent, initiatorEphemeralSecretKey, provider) {
-    const Rbytes = getBytes(responseEvent.responderEphemeralR); // hex -> Uint8Array
-    const expectedTag = computeTagFromInitiator(initiatorEphemeralSecretKey, Rbytes);
-    if (expectedTag !== responseEvent.inResponseTo) {
-        return { isValid: false };
-    }
+export async function verifyAndExtractHandshakeResponseKeys(responseEvent, initiatorEphemeralSecretKey, initiatorKemSecretKey, provider, ctx) {
+    // Decrypt first to get kemCiphertext
     const extractedResponse = decryptAndExtractHandshakeKeys(responseEvent.ciphertext, initiatorEphemeralSecretKey);
     if (!extractedResponse) {
         return { isValid: false };
     }
-    const isValid = await verifyHandshakeResponseIdentity(responseEvent, extractedResponse.identityPubKey, initiatorEphemeralSecretKey, provider);
+    if (!extractedResponse.kemCiphertext) {
+        return { isValid: false };
+    }
+    // Decapsulate and verify hybrid tag
+    const Rbytes = getBytes(responseEvent.responderEphemeralR);
+    const kemSecret = kem.decapsulate(extractedResponse.kemCiphertext, initiatorKemSecretKey);
+    const expectedTag = computeHybridTagFromInitiator(initiatorEphemeralSecretKey, Rbytes, kemSecret);
+    if (expectedTag !== responseEvent.inResponseTo) {
+        return { isValid: false };
+    }
+    const isValid = await verifyHandshakeResponseIdentity(responseEvent, extractedResponse.identityPubKey, initiatorEphemeralSecretKey, provider, ctx);
     if (!isValid) {
         return { isValid: false };
     }
@@ -165,22 +178,8 @@ export async function verifyAndExtractHandshakeResponseKeys(responseEvent, initi
             identityPubKey: extractedResponse.identityPubKey,
             signingPubKey: extractedResponse.signingPubKey,
             ephemeralPubKey: extractedResponse.ephemeralPubKey,
+            kemCiphertext: extractedResponse.kemCiphertext,
             note: extractedResponse.note,
         },
     };
 }
-/**
- * Verify and derive duplex topics from a long-term DH secret.
- * - Accepts either `tag` (inResponseTo) or a raw salt as KDF input.
- * - Recomputes topicOut/topicIn deterministically from the identity DH.
- * - If topicInfo is provided (from HSR), also verify the checksum.
- * - Used by the initiator after decrypting a HandshakeResponse to confirm responder’s topics.
- */
-export function verifyDerivedDuplexTopics({ myIdentitySecretKey, theirIdentityPubKey, tag, salt, topicInfo }) {
-    const s = salt ?? (tag ? getBytes(tag) : undefined);
-    if (!s)
-        throw new Error("Provide either salt or inResponseTo");
-    const { topicOut, topicIn, checksum } = deriveDuplexTopics(myIdentitySecretKey, theirIdentityPubKey, s);
-    const ok = topicInfo ? verifyDuplexTopicsChecksum(topicOut, topicIn, topicInfo.chk) : undefined;
-    return { topics: { topicOut, topicIn }, ok };
-}

package/dist/src/addresses.d.ts

@@ -0,0 +1,20 @@
+export interface ChainConfig {
+    verbethProxy: `0x${string}`;
+    verbethImpl: `0x${string}`;
+    creationBlock: number;
+    moduleSetupHelper?: `0x${string}`;
+}
+export declare const VERBETH_CONFIG: ChainConfig;
+export declare const MODULE_SETUP_HELPERS: Record<number, `0x${string}`>;
+export declare function getVerbethAddress(): `0x${string}`;
+export declare function getCreationBlock(): number;
+export declare function getModuleSetupHelper(chainId: number): `0x${string}` | undefined;
+export declare function isModuleSetupSupported(chainId: number): boolean;
+export declare const SCAN_DEFAULTS: {
+    readonly INITIAL_SCAN_BLOCKS: 1000;
+    readonly MAX_RETRIES: 3;
+    readonly MAX_RANGE_PROVIDER: 2000;
+    readonly CHUNK_SIZE: 2000;
+    readonly REAL_TIME_BUFFER: 3;
+};
+//# sourceMappingURL=addresses.d.ts.map

package/dist/src/addresses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addresses.d.ts","sourceRoot":"","sources":["../../src/addresses.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,KAAK,MAAM,EAAE,CAAC;IAC5B,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;CACnC;AAGD,eAAO,MAAM,cAAc,EAAE,WAInB,CAAC;AAGX,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,MAAM,EAAE,CAGrD,CAAC;AAGX,wBAAgB,iBAAiB,IAAI,KAAK,MAAM,EAAE,CAEjD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,GAAG,SAAS,CAE/E;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/D;AAGD,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC"}

package/dist/src/addresses.js

@@ -0,0 +1,33 @@
+// packages/sdk/src/addresses.ts
+// Deterministic deployment - same addresses on Base Mainnet & Sepolia
+export const VERBETH_CONFIG = {
+    verbethProxy: '0x82C9c5475D63e4C9e959280e9066aBb24973a663',
+    verbethImpl: '0x51670aB6eDE1d1B11C654CCA53b7D42080802326',
+    creationBlock: 36053269,
+};
+// Per-chain module setup helpers (for Safe session module)
+export const MODULE_SETUP_HELPERS = {
+    8453: '0xc022F74924BDB4b62D830234d89b066359bF67c0', // Base Mainnet
+    84532: '0xbd59Fea46D308eDF3b75C22a6f64AC68feFc731A', // Base Sepolia
+};
+// Helper functions
+export function getVerbethAddress() {
+    return VERBETH_CONFIG.verbethProxy;
+}
+export function getCreationBlock() {
+    return VERBETH_CONFIG.creationBlock;
+}
+export function getModuleSetupHelper(chainId) {
+    return MODULE_SETUP_HELPERS[chainId];
+}
+export function isModuleSetupSupported(chainId) {
+    return chainId in MODULE_SETUP_HELPERS;
+}
+// Scanning defaults (chain-agnostic)
+export const SCAN_DEFAULTS = {
+    INITIAL_SCAN_BLOCKS: 1000,
+    MAX_RETRIES: 3,
+    MAX_RANGE_PROVIDER: 2000,
+    CHUNK_SIZE: 2000,
+    REAL_TIME_BUFFER: 3,
+};

package/dist/src/client/HsrTagIndex.d.ts

@@ -0,0 +1,77 @@
+export interface PendingContactEntry {
+    address: string;
+    handshakeEphemeralSecret: Uint8Array;
+    kemSecretKey: Uint8Array;
+}
+/**
+ * Index for efficient HSR tag matching.
+ *
+ * When an HSR arrives, we need to find which pending contact it belongs to.
+ * This requires computing tag = computeTagFromInitiator(secret, R) for each
+ * pending contact until we find a match.
+ *
+ * This class caches the computed tags per (contact, R) pair, making
+ * subsequent lookups O(1) after the first computation.
+ *
+ * @example
+ * ```typescript
+ * const hsrIndex = new HsrTagIndex();
+ *
+ * // When pending contacts change
+ * hsrIndex.rebuild(pendingContacts.map(c => ({
+ *   address: c.address,
+ *   handshakeEphemeralSecret: c.handshakeEphemeralSecret
+ * })));
+ *
+ * // Matching O(1) after first computation for each R
+ * const matchedAddress = hsrIndex.matchByTag(inResponseToTag, R);
+ * ```
+ */
+export declare class HsrTagIndex {
+    private entries;
+    private tagToAddress;
+    /**
+     * Rebuild the index with a new set of pending contacts.
+     *
+     * Preserves cached tag computations for contacts that remain.
+     * Clears entries for contacts no longer in the list.
+     *
+     * @param contacts - Current pending contacts
+     */
+    rebuild(contacts: PendingContactEntry[]): void;
+    /**
+     * Add a single pending contact without full rebuild.
+     *
+     * @param contact - Contact to add
+     */
+    addContact(contact: PendingContactEntry): void;
+    /**
+     * Remove a contact from the index.
+     *
+     * @param address - Address of contact to remove
+     */
+    removeContact(address: string): void;
+    clear(): void;
+    /**
+     * Match an HSR by its tag using hybrid (PQ-secure) computation.
+     *
+     * Decrypts the payload internally to extract kemCiphertext, then
+     * decapsulates and computes the hybrid tag for matching.
+     *
+     * @param inResponseToTag - The tag from the HSR event
+     * @param R - Responder's ephemeral public key (from HSR event)
+     * @param encryptedPayload - JSON string of the encrypted HSR payload
+     * @returns Address of matching contact, or null if no match
+     */
+    matchByTag(inResponseToTag: `0x${string}`, R: Uint8Array, encryptedPayload: string): string | null;
+    /**
+     * Get the number of indexed contacts.
+     */
+    get size(): number;
+    /**
+     * Check if a contact is in the index.
+     */
+    hasContact(address: string): boolean;
+    private secretsEqual;
+}
+//# sourceMappingURL=HsrTagIndex.d.ts.map

package/dist/src/client/HsrTagIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HsrTagIndex.d.ts","sourceRoot":"","sources":["../../../src/client/HsrTagIndex.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB,EAAE,UAAU,CAAC;IACrC,YAAY,EAAE,UAAU,CAAC;CAC1B;AAQD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,YAAY,CAAkC;IAEtD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,IAAI;IAuB9C;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAc9C;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAcpC,KAAK,IAAI,IAAI;IAKb;;;;;;;;;;OAUG;IACH,UAAU,CACR,eAAe,EAAE,KAAK,MAAM,EAAE,EAC9B,CAAC,EAAE,UAAU,EACb,gBAAgB,EAAE,MAAM,GACvB,MAAM,GAAG,IAAI;IAyBhB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIpC,OAAO,CAAC,YAAY;CAOrB"}

package/dist/src/client/HsrTagIndex.js

@@ -0,0 +1,157 @@
+// packages/sdk/src/client/HsrTagIndex.ts
+/**
+ * Index for O(1) HSR (Handshake Response) matching.
+ *
+ * Caches computed tags for pending contacts to avoid O(n) loops
+ * when matching incoming handshake responses.
+ */
+import { computeHybridTagFromInitiator, decryptHandshakeResponse } from '../crypto.js';
+import { kem } from '../pq/kem.js';
+/**
+ * Index for efficient HSR tag matching.
+ *
+ * When an HSR arrives, we need to find which pending contact it belongs to.
+ * This requires computing tag = computeTagFromInitiator(secret, R) for each
+ * pending contact until we find a match.
+ *
+ * This class caches the computed tags per (contact, R) pair, making
+ * subsequent lookups O(1) after the first computation.
+ *
+ * @example
+ * ```typescript
+ * const hsrIndex = new HsrTagIndex();
+ *
+ * // When pending contacts change
+ * hsrIndex.rebuild(pendingContacts.map(c => ({
+ *   address: c.address,
+ *   handshakeEphemeralSecret: c.handshakeEphemeralSecret
+ * })));
+ *
+ * // Matching O(1) after first computation for each R
+ * const matchedAddress = hsrIndex.matchByTag(inResponseToTag, R);
+ * ```
+ */
+export class HsrTagIndex {
+    constructor() {
+        this.entries = new Map();
+        this.tagToAddress = new Map();
+    }
+    /**
+     * Rebuild the index with a new set of pending contacts.
+     *
+     * Preserves cached tag computations for contacts that remain.
+     * Clears entries for contacts no longer in the list.
+     *
+     * @param contacts - Current pending contacts
+     */
+    rebuild(contacts) {
+        const newEntries = new Map();
+        for (const contact of contacts) {
+            const existing = this.entries.get(contact.address);
+            if (existing &&
+                this.secretsEqual(existing.secret, contact.handshakeEphemeralSecret) &&
+                this.secretsEqual(existing.kemSecretKey, contact.kemSecretKey)) {
+                newEntries.set(contact.address, existing);
+            }
+            else {
+                newEntries.set(contact.address, {
+                    address: contact.address,
+                    secret: contact.handshakeEphemeralSecret,
+                    kemSecretKey: contact.kemSecretKey,
+                });
+            }
+        }
+        // Keep tagToAddress cache - it's still valid for already computed tags
+        this.entries = newEntries;
+    }
+    /**
+     * Add a single pending contact without full rebuild.
+     *
+     * @param contact - Contact to add
+     */
+    addContact(contact) {
+        const existing = this.entries.get(contact.address);
+        if (!existing ||
+            !this.secretsEqual(existing.secret, contact.handshakeEphemeralSecret) ||
+            !this.secretsEqual(existing.kemSecretKey, contact.kemSecretKey)) {
+            this.entries.set(contact.address, {
+                address: contact.address,
+                secret: contact.handshakeEphemeralSecret,
+                kemSecretKey: contact.kemSecretKey,
+            });
+        }
+    }
+    /**
+     * Remove a contact from the index.
+     *
+     * @param address - Address of contact to remove
+     */
+    removeContact(address) {
+        const entry = this.entries.get(address);
+        if (entry) {
+            // Remove any cached tags for this address
+            for (const [tag, addr] of this.tagToAddress) {
+                if (addr === address) {
+                    this.tagToAddress.delete(tag);
+                }
+            }
+            this.entries.delete(address);
+        }
+    }
+    clear() {
+        this.entries.clear();
+        this.tagToAddress.clear();
+    }
+    /**
+     * Match an HSR by its tag using hybrid (PQ-secure) computation.
+     *
+     * Decrypts the payload internally to extract kemCiphertext, then
+     * decapsulates and computes the hybrid tag for matching.
+     *
+     * @param inResponseToTag - The tag from the HSR event
+     * @param R - Responder's ephemeral public key (from HSR event)
+     * @param encryptedPayload - JSON string of the encrypted HSR payload
+     * @returns Address of matching contact, or null if no match
+     */
+    matchByTag(inResponseToTag, R, encryptedPayload) {
+        // Cache check
+        const cachedAddress = this.tagToAddress.get(inResponseToTag);
+        if (cachedAddress) {
+            return cachedAddress;
+        }
+        // For each contact: decrypt → extract kemCiphertext → decapsulate → compute hybrid tag
+        for (const [address, entry] of this.entries) {
+            const decrypted = decryptHandshakeResponse(encryptedPayload, entry.secret);
+            if (!decrypted || !decrypted.kemCiphertext)
+                continue;
+            const kemSecret = kem.decapsulate(decrypted.kemCiphertext, entry.kemSecretKey);
+            const tag = computeHybridTagFromInitiator(entry.secret, R, kemSecret);
+            this.tagToAddress.set(tag, address);
+            if (tag === inResponseToTag) {
+                return address;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get the number of indexed contacts.
+     */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Check if a contact is in the index.
+     */
+    hasContact(address) {
+        return this.entries.has(address);
+    }
+    secretsEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i])
+                return false;
+        }
+        return true;
+    }
+}

package/dist/src/client/PendingManager.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Internal Pending Message Coordinator.
+ *
+ * Manages the lifecycle of outbound messages:
+ * - Creating pending records before tx submission
+ * - Updating status on submission
+ * - Matching confirmations by txHash
+ * - Cleaning up after confirmation or failure
+ */
+import { PendingStore, PendingMessage } from './types.js';
+export interface CreatePendingParams {
+    id: string;
+    conversationId: string;
+    topic: string;
+    payloadHex: string;
+    plaintext: string;
+    sessionStateBefore: string;
+    sessionStateAfter: string;
+    createdAt: number;
+}
+export declare class PendingManager {
+    private store;
+    constructor(store: PendingStore);
+    /**
+     * Create and save a pending message record.
+     * Called right before submitting a transaction.
+     */
+    create(params: CreatePendingParams): Promise<PendingMessage>;
+    /**
+     * Mark as submitted with transaction hash.
+     * Called immediately after tx is broadcast.
+     */
+    markSubmitted(id: string, txHash: string): Promise<void>;
+    /**
+     * Mark as failed.
+     * Called when tx submission fails.
+     * Note: Ratchet slot is already burned (session was committed).
+     */
+    markFailed(id: string): Promise<void>;
+    get(id: string): Promise<PendingMessage | null>;
+    getByTxHash(txHash: string): Promise<PendingMessage | null>;
+    getByConversation(conversationId: string): Promise<PendingMessage[]>;
+    /**
+     * Finalize and delete.
+     * Called when we see our MessageSent event on-chain.
+     *
+     * @returns The finalized pending message, or null if not found
+     */
+    finalize(id: string): Promise<PendingMessage | null>;
+    /**
+     * Delete a pending message without finalizing.
+     * Used for cleanup on failure or cancellation.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Clean up stale pending messages.
+     * Called periodically to remove old failed/stuck records.
+     *
+     * @param conversationId - Conversation to clean up
+     * @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
+     * @returns Number of records cleaned up
+     */
+    cleanupStale(conversationId: string, maxAgeMs?: number): Promise<number>;
+}
+//# sourceMappingURL=PendingManager.d.ts.map

package/dist/src/client/PendingManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PendingManager.d.ts","sourceRoot":"","sources":["../../../src/client/PendingManager.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAEzE,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,YAAY;IAEvC;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAUlE;;;OAGG;IACG,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D;;;;OAIG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAK/C,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAI3D,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK1E;;;;;OAKG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAU1D;;;OAGG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;;OAOG;IACG,YAAY,CAChB,cAAc,EAAE,MAAM,EACtB,QAAQ,GAAE,MAA4B,GACrC,OAAO,CAAC,MAAM,CAAC;CAcnB"}

package/dist/src/client/PendingManager.js

@@ -0,0 +1,84 @@
+// packages/sdk/src/client/PendingManager.ts
+export class PendingManager {
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Create and save a pending message record.
+     * Called right before submitting a transaction.
+     */
+    async create(params) {
+        const pending = {
+            ...params,
+            txHash: null,
+            status: 'preparing',
+        };
+        await this.store.save(pending);
+        return pending;
+    }
+    /**
+     * Mark as submitted with transaction hash.
+     * Called immediately after tx is broadcast.
+     */
+    async markSubmitted(id, txHash) {
+        await this.store.updateStatus(id, 'submitted', txHash);
+    }
+    /**
+     * Mark as failed.
+     * Called when tx submission fails.
+     * Note: Ratchet slot is already burned (session was committed).
+     */
+    async markFailed(id) {
+        await this.store.updateStatus(id, 'failed');
+    }
+    async get(id) {
+        return this.store.get(id);
+    }
+    async getByTxHash(txHash) {
+        return this.store.getByTxHash(txHash);
+    }
+    async getByConversation(conversationId) {
+        return this.store.getByConversation(conversationId);
+    }
+    /**
+     * Finalize and delete.
+     * Called when we see our MessageSent event on-chain.
+     *
+     * @returns The finalized pending message, or null if not found
+     */
+    async finalize(id) {
+        const pending = await this.store.get(id);
+        if (!pending) {
+            return null;
+        }
+        await this.store.delete(id);
+        return pending;
+    }
+    /**
+     * Delete a pending message without finalizing.
+     * Used for cleanup on failure or cancellation.
+     */
+    async delete(id) {
+        await this.store.delete(id);
+    }
+    /**
+     * Clean up stale pending messages.
+     * Called periodically to remove old failed/stuck records.
+     *
+     * @param conversationId - Conversation to clean up
+     * @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
+     * @returns Number of records cleaned up
+     */
+    async cleanupStale(conversationId, maxAgeMs = 24 * 60 * 60 * 1000) {
+        const pending = await this.store.getByConversation(conversationId);
+        const cutoff = Date.now() - maxAgeMs;
+        let cleaned = 0;
+        for (const p of pending) {
+            if (p.createdAt < cutoff) {
+                await this.store.delete(p.id);
+                cleaned++;
+            }
+        }
+        return cleaned;
+    }
+}