@verbeth/sdk 0.1.4 → 0.1.6

package/README.md

@@ -1,191 +1,43 @@
 # @verbeth/sdk
 
-Verbeth enables secure, E2EE messaging using Ethereum event logs as the only transport layer. No servers, no relays—just the blockchain.
-
-## Features
-
-- **End-to-end encryption** using NaCl Box (X25519 + XSalsa20-Poly1305)
-- **Forward secrecy** with ephemeral keys per message
-- **Handshake protocol** for secure key exchange
-- **Privacy-focused** with minimal metadata via `recipientHash`
-- **EOA & Smart Account support** (ERC-1271/6492 compatible)
-- **Fully on-chain** - no centralized infrastructure
-
-## Installation
+End-to-end encrypted messaging over public EVM blockchains.
 
+### Install
 ```bash
-npm install @verbeth/sdk ethers tweetnacl
+npm install @verbeth/sdk
 ```
 
-## Quick Start
-
-### 1. Initialize with VerbethClient (Recommended)
-
-```typescript
-import { VerbethClient, ExecutorFactory, deriveIdentityKeyPairWithProof } from '@verbeth/sdk';
-import { Contract, BrowserProvider } from 'ethers';
-import { LogChainV1__factory } from '@verbeth/contracts/typechain-types';
+### Quickstart
+```ts
+import {
+  createVerbethClient,
+  deriveIdentityKeyPairWithProof,
+  ExecutorFactory,
+  getVerbethAddress
+} from '@verbeth/sdk';
+import { ethers } from 'ethers';
 
-// Setup
-const provider = new BrowserProvider(window.ethereum);
+const provider = new ethers.BrowserProvider(window.ethereum);
 const signer = await provider.getSigner();
 const address = await signer.getAddress();
 
-// Create contract instance
-const contract = LogChainV1__factory.connect(LOGCHAIN_ADDRESS, signer);
-
-// Derive identity keys (done once, then stored)
-const { identityKeyPair, identityProof } = await deriveIdentityKeyPairWithProof(signer);
-
-// Create executor (handles transaction submission)
-const executor = ExecutorFactory.createEOA(contract);
+const { identityKeyPair, identityProof } = await deriveIdentityKeyPairWithProof(signer, address);
 
-// Initialize client
-const client = new VerbethClient({
-  executor,
-  identityKeyPair,
-  identityProof,
+const contract = new ethers.Contract(getVerbethAddress(), VerbethABI, signer);
+const client = createVerbethClient({
+  address,
   signer,
-  address
-});
-
-// Send a handshake to start chatting
-const { tx, ephemeralKeyPair } = await client.sendHandshake(
-  '0xRecipientAddress...',
-  'Hello! Want to chat?'
-);
-
-// Store ephemeralKeyPair. you'll just need it to decrypt the handshake response!
-
-// Accept a handshake
-const { tx, duplexTopics } = await client.acceptHandshake(
-  handshakeEvent.ephemeralPubKey,
-  handshakeEvent.identityPubKey,
-  'Sure, lets chat!'
-);
-
-// Send encrypted messages
-await client.sendMessage(
-  duplexTopics.topicOut,
-  recipientIdentityPubKey,
-  'This message is encrypted!'
-);
-
-// Decrypt received messages
-const decrypted = await client.decryptMessage(
-  messageEvent.ciphertext,
-  senderIdentityPubKey
-);
-```
-
-### 2. Low-level API
-
-For more control, use the low-level functions:
-
-```typescript
-import {
-  initiateHandshake,
-  respondToHandshake,
-  sendEncryptedMessage,
-  decryptMessage,
-  deriveIdentityKeyPairWithProof
-} from '@verbeth/sdk';
-
-// Generate identity keys
-const { identityKeyPair, identityProof } = await deriveIdentityKeyPairWithProof(signer);
-
-// Initiate handshake
-const ephemeralKeyPair = nacl.box.keyPair();
-const tx = await initiateHandshake({
-  executor,
-  recipientAddress: '0xBob...',
-  ephemeralPubKey: ephemeralKeyPair.publicKey,
   identityKeyPair,
   identityProof,
-  plaintextPayload: 'Hi Bob!'
-});
-
-// Send encrypted message
-await sendEncryptedMessage({
-  executor,
-  topic: derivedTopic,
-  message: 'Secret message',
-  recipientPubKey: bobsIdentityKey,
-  senderAddress: myAddress,
-  senderSignKeyPair: identityKeyPair,
-  timestamp: Date.now()
+  executor: ExecutorFactory.createEOA(contract),
 });
 
-// Decrypt message
-const plaintext = decryptMessage(
-  ciphertext,
-  senderIdentityPubKey,
-  myIdentityKeyPair.secretKey
-);
-```
-
-## Smart Account Support
-
-Verbeth works with ERC-4337 smart accounts:
-
-```typescript
-import { ExecutorFactory } from '@verbeth/sdk';
-
-// For UserOp-based execution
-const executor = ExecutorFactory.createUserOp(
-  contract,
-  bundler,
-  smartAccount,
-  signer
-);
-
-// For direct EntryPoint execution
-const executor = ExecutorFactory.createDirectEntryPoint(
-  contract,
-  entryPoint,
-  smartAccountAddress,
-  signer
-);
+await client.sendMessage(conversationId, 'Hello, encrypted world!');
 ```
 
-## Contract Addresses
-
-**LogChainV1 Singleton:** `0x41a3eaC0d858028E9228d1E2092e6178fc81c4f0`
-
-**ERC1967Proxy:** `0x62720f39d5Ec6501508bDe4D152c1E13Fd2F6707`
-
-## How It Works
-
-1. **Identity Keys**: Each account derives long-term X25519 (encryption) + Ed25519 (signing) keys bound to their address via signature
-2. **Handshake**: Alice sends her ephemeral key + identity proof to Bob via a `Handshake` event
-3. **Response**: Bob verifies Alice's identity and responds with his keys + duplex topics
-4. **Messaging**: Both parties derive shared topics and exchange encrypted messages via `MessageSent` events
-5. **Decryption**: Recipients monitor their inbound topic and decrypt with their identity key
-
-
-## Security Considerations
-
-- **Forward Secrecy**: Fresh ephemeral keys per message provide sender-side forward secrecy
-- **Identity Binding**: Addresses are cryptographically bound to long-term keys via signature
-- **Non-Repudiation**: Optional Ed25519 signatures prove message origin
-- **Privacy**: RecipientHash hides recipient identity; duplex topics separate communication channels
-
-⚠️ **Note**: Current design provides sender-side forward secrecy. Recipient-side FS requires ephemeral↔ephemeral or session ratcheting (e.g., Double Ratchet).
-
-## Built With
-
-- [TweetNaCl](https://tweetnacl.js.org/) - Encryption primitives
-- [Ethers v6](https://docs.ethers.org/v6/) - Ethereum interactions
-- [Viem](https://viem.sh/) - EIP-1271/6492 verification
-- [Noble Curves](https://github.com/paulmillr/noble-curves) - Elliptic curve operations
-
-## Examples
-
-Check out the [demo application](https://github.com/okrame/verbeth-sdk/tree/main/apps/demo) for a complete implementation.
-
 ## Documentation
 
-For detailed protocol documentation, security analysis, and improvement proposals, see the [main repository](https://github.com/okrame/verbeth-sdk).
+For detailed protocol documentation, see [docs.verbeth.xyz](https://docs.verbeth.xyz).
 
 ## License
 

package/dist/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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;
+    }
+}