@arkade-os/sdk 0.2.3 → 0.3.0-alpha.0

package/README.md

@@ -1,8 +1,9 @@
 # Arkade TypeScript SDK
+
 The Arkade SDK is a TypeScript library for building Bitcoin wallets with support for both on-chain and off-chain transactions via the Ark protocol.
 
 [![TypeScript Documentation](https://img.shields.io/badge/TypeScript-Documentation-blue?style=flat-square)](https://arkade-os.github.io/ts-sdk/)
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/arkade-os/ts-sdk)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ark-ts-sdk)
 
 ## Installation
 
@@ -22,16 +23,20 @@ const identity = SingleKey.fromHex('your_private_key_hex')
 
 // Create a wallet with Ark support
 const wallet = await Wallet.create({
-  identity: identity,
-  // Esplora API, can be left empty mempool.space API will be used
+  identity,
+  // Esplora API, can be left empty - mempool.space API will be used
   esploraUrl: 'https://mutinynet.com/api', 
   arkServerUrl: 'https://mutinynet.arkade.sh',
+  // Optional: specify storage adapter (defaults to InMemoryStorageAdapter)
+  // storage: new LocalStorageAdapter() // for browser persistence
 })
 ```
 
 ### Receiving Bitcoin
 
 ```typescript
+import { waitForIncomingFunds } from '@arkade-os/sdk'
+
 // Get wallet addresses
 const arkAddress = await wallet.getAddress()
 const boardingAddress = await wallet.getBoardingAddress()
@@ -40,17 +45,17 @@ console.log('Boarding Address:', boardingAddress)
 
 const incomingFunds = await waitForIncomingFunds(wallet)
 if (incomingFunds.type === "vtxo") {
-  // virtual coins received 
+  // Virtual coins received 
   console.log("VTXOs: ", incomingFunds.vtxos)
 } else if (incomingFunds.type === "utxo") {
-  // boarding coins received
+  // Boarding coins received
   console.log("UTXOs: ", incomingFunds.coins)
 }
 ```
 
 ### Onboarding
 
-Onboarding allows you to swap onchain funds into VTXOs
+Onboarding allows you to swap on-chain funds into VTXOs:
 
 ```typescript
 import { Ramps } from '@arkade-os/sdk'
@@ -88,9 +93,9 @@ const txid = await wallet.sendBitcoin({
 })
 ```
 
-### Batch Settlements 
+### Batch Settlements
 
-This can be used to move preconfirmed balances into finalized balances, to convert manually UTXOs and VTXOs.
+This can be used to move preconfirmed balances into finalized balances and to manually convert UTXOs and VTXOs.
 
 ```typescript
 // For settling transactions
@@ -127,7 +132,7 @@ console.log('History:', history)
 
 ### Offboarding
 
-Collaborative exit or "offboarding" allows you to withdraw your virtual funds to an onchain address.
+Collaborative exit or "offboarding" allows you to withdraw your virtual funds to an on-chain address:
 
 ```typescript
 import { Ramps } from '@arkade-os/sdk'
@@ -145,11 +150,14 @@ Unilateral exit allows you to withdraw your funds from the Ark protocol back to
 #### Step 1: Unrolling VTXOs
 
 ```typescript
-import { Unroll, OnchainWallet } from '@arkade-os/sdk'
+import { Unroll, OnchainWallet, SingleKey } from '@arkade-os/sdk'
+
+// Create an identity for the onchain wallet
+const onchainIdentity = SingleKey.fromHex('your_onchain_private_key_hex');
 
 // Create an onchain wallet to pay for P2A outputs in VTXO branches
 // OnchainWallet implements the AnchorBumper interface
-const onchainWallet = new OnchainWallet(wallet.identity, 'regtest');
+const onchainWallet = await OnchainWallet.create(onchainIdentity, 'regtest');
 
 // Unroll a specific VTXO
 const vtxo = { txid: 'your_vtxo_txid', vout: 0 };
@@ -177,6 +185,7 @@ for await (const step of session) {
 ```
 
 The unrolling process works by:
+
 - Traversing the transaction chain from the root (most recent) to the leaf (oldest)
 - Broadcasting each transaction that isn't already on-chain
 - Waiting for confirmations between steps
@@ -196,6 +205,7 @@ await Unroll.completeUnroll(
 ```
 
 **Important Notes:**
+
 - Each VTXO may require multiple unroll steps depending on the transaction chain length
 - Each unroll step must be confirmed before proceeding to the next
 - The `completeUnroll` method can only be called after VTXOs are fully unrolled and the timelock has expired
@@ -203,42 +213,103 @@ await Unroll.completeUnroll(
 
 ### Running the wallet in a service worker
 
-1. Create a service worker file
+**Ultra-simplified setup!** We handle all the complex service worker registration and identity management for you:
+
+```typescript
+// SIMPLE SETUP with identity! 🎉
+import { ServiceWorkerWallet, SingleKey } from '@arkade-os/sdk';
+
+// Create your identity
+const identity = SingleKey.fromHex('your_private_key_hex');
+// Or generate a new one:
+// const identity = SingleKey.fromRandomBytes();
+
+const wallet = await ServiceWorkerWallet.setup({
+  serviceWorkerPath: '/service-worker.js',
+  arkServerUrl: 'https://mutinynet.arkade.sh',
+  identity
+});
+
+// That's it! Ready to use immediately:
+const address = await wallet.getAddress();
+const balance = await wallet.getBalance();
+```
+
+You'll also need to create a service worker file:
 
 ```typescript
-// service-worker.ts
+// service-worker.js
 import { Worker } from '@arkade-os/sdk'
 
 // Worker handles communication between the main thread and service worker
 new Worker().start()
 ```
 
-2. Instantiate the ServiceWorkerWallet
+### Storage Adapters
+
+Choose the appropriate storage adapter for your environment:
 
 ```typescript
-// specify the path to the service worker file
-// this will automatically register the service worker
-const serviceWorker = await setupServiceWorker('/service-worker.js')
-const wallet = new ServiceWorkerWallet(serviceWorker)
-
-// Initialize the wallet
-await wallet.init({
-  privateKey: 'your_private_key_hex',
-  // Esplora API, can be left empty mempool.space API will be used
-  esploraUrl: 'https://mutinynet.com/api', 
-  // OPTIONAL Ark Server connection information
+import { 
+  SingleKey,
+  Wallet,
+  InMemoryStorageAdapter,     // Works everywhere, data lost on restart
+} from '@arkade-os/sdk'
+
+// Import additional storage adapters as needed:
+import { LocalStorageAdapter } from '@arkade-os/sdk/adapters/localStorage'        // Browser/PWA persistent storage  
+import { IndexedDBStorageAdapter } from '@arkade-os/sdk/adapters/indexedDB'      // Browser/PWA/Service Worker advanced storage
+import { AsyncStorageAdapter } from '@arkade-os/sdk/adapters/asyncStorage'      // React Native persistent storage
+import { FileSystemStorageAdapter } from '@arkade-os/sdk/adapters/fileSystem'   // Node.js file-based storage
+
+// Node.js
+const storage = new FileSystemStorageAdapter('./wallet-data')
+
+// Browser/PWA
+const storage = new LocalStorageAdapter()
+// or for advanced features:
+const storage = new IndexedDBStorageAdapter('my-app', 1)
+
+// React Native  
+const storage = new AsyncStorageAdapter()
+
+// Service Worker
+const storage = new IndexedDBStorageAdapter('service-worker-wallet', 1)
+
+// Load identity from storage (simple pattern everywhere)
+const privateKeyHex = await storage.getItem('private-key')
+const identity = SingleKey.fromHex(privateKeyHex)
+
+// Create wallet (same API everywhere)
+const wallet = await Wallet.create({
+  identity,
   arkServerUrl: 'https://mutinynet.arkade.sh',
+  storage // optional
 })
+```
 
-// check service worker status
-const status = await wallet.getStatus()
-console.log('Service worker status:', status.walletInitialized)
+### Repository Pattern
 
-// clear wallet data stored in the service worker memory
-await wallet.clear()
-```
+Access low-level data management through repositories:
 
-_For complete API documentation, visit our [TypeScript documentation](https://arkade-os.github.io/ts-sdk/)._
+```typescript
+// VTXO management (automatically cached for performance)
+const addr = await wallet.getAddress()
+const vtxos = await wallet.walletRepository.getVtxos(addr)
+await wallet.walletRepository.saveVtxos(addr, vtxos)
+
+// Contract data for SDK integrations
+await wallet.contractRepository.setContractData('my-contract', 'status', 'active')
+const status = await wallet.contractRepository.getContractData('my-contract', 'status')
+
+// Collection management for related data
+await wallet.contractRepository.saveToContractCollection(
+  'swaps',
+  { id: 'swap-1', amount: 50000, type: 'reverse' },
+  'id' // key field
+)
+const swaps = await wallet.contractRepository.getContractCollection('swaps')
+```
 
 ## Development
 
@@ -251,17 +322,17 @@ _For complete API documentation, visit our [TypeScript documentation](https://ar
 
 1. Install dependencies:
 
-```bash
-pnpm install
-pnpm format
-pnpm lint
-```
+   ```bash
+   pnpm install
+   pnpm format
+   pnpm lint
+   ```
 
-2. Install nigiri for integration tests:
+1. Install nigiri for integration tests:
 
-```bash
-curl https://getnigiri.vulpem.com | bash
-```
+   ```bash
+   curl https://getnigiri.vulpem.com | bash
+   ```
 
 ### Running Tests
 
@@ -296,9 +367,9 @@ pnpm test:coverage
 ### Building the documentation
 
 ```bash
-# Build the TS doc
+# Build the TypeScript documentation
 pnpm docs:build
-# open the docs in the browser
+# Open the docs in the browser
 pnpm docs:open
 ```
 

package/dist/cjs/adapters/asyncStorage.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncStorageAdapter = void 0;
+var asyncStorage_1 = require("../storage/asyncStorage");
+Object.defineProperty(exports, "AsyncStorageAdapter", { enumerable: true, get: function () { return asyncStorage_1.AsyncStorageAdapter; } });

package/dist/cjs/adapters/fileSystem.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSystemStorageAdapter = void 0;
+var fileSystem_1 = require("../storage/fileSystem");
+Object.defineProperty(exports, "FileSystemStorageAdapter", { enumerable: true, get: function () { return fileSystem_1.FileSystemStorageAdapter; } });

package/dist/cjs/adapters/indexedDB.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexedDBStorageAdapter = void 0;
+var indexedDB_1 = require("../storage/indexedDB");
+Object.defineProperty(exports, "IndexedDBStorageAdapter", { enumerable: true, get: function () { return indexedDB_1.IndexedDBStorageAdapter; } });

package/dist/cjs/adapters/localStorage.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalStorageAdapter = void 0;
+var localStorage_1 = require("../storage/localStorage");
+Object.defineProperty(exports, "LocalStorageAdapter", { enumerable: true, get: function () { return localStorage_1.LocalStorageAdapter; } });

package/dist/cjs/bip322/index.js

@@ -4,7 +4,7 @@ exports.BIP322 = void 0;
 exports.craftToSpendTx = craftToSpendTx;
 const btc_signer_1 = require("@scure/btc-signer");
 const errors_1 = require("./errors");
-const secp256k1_1 = require("@noble/curves/secp256k1");
+const secp256k1_js_1 = require("@noble/curves/secp256k1.js");
 const base_1 = require("@scure/base");
 /**
  * BIP-322 signature implementation for Bitcoin message signing.
@@ -174,5 +174,5 @@ function craftToSignTx(toSpend, inputs, outputs) {
     return tx;
 }
 function hashMessage(message) {
-    return secp256k1_1.schnorr.utils.taggedHash(TAG_BIP322, new TextEncoder().encode(message));
+    return secp256k1_js_1.schnorr.utils.taggedHash(TAG_BIP322, new TextEncoder().encode(message));
 }

package/dist/cjs/identity/index.js

@@ -1,2 +1,17 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./singleKey"), exports);

package/dist/cjs/identity/singleKey.js

@@ -5,6 +5,7 @@ const utils_1 = require("@scure/btc-signer/utils");
 const base_1 = require("@scure/base");
 const btc_signer_1 = require("@scure/btc-signer");
 const signingSession_1 = require("../tree/signingSession");
+const secp256k1_1 = require("@noble/secp256k1");
 const ZERO_32 = new Uint8Array(32).fill(0);
 const ALL_SIGHASH = Object.values(btc_signer_1.SigHash).filter((x) => typeof x === "number");
 /**
@@ -18,6 +19,9 @@ const ALL_SIGHASH = Object.values(btc_signer_1.SigHash).filter((x) => typeof x =
  * // Create from raw bytes
  * const key = SingleKey.fromPrivateKey(privateKeyBytes);
  *
+ * // Create random key
+ * const randomKey = SingleKey.fromRandomBytes();
+ *
  * // Sign a transaction
  * const signedTx = await key.sign(transaction);
  * ```
@@ -32,6 +36,17 @@ class SingleKey {
     static fromHex(privateKeyHex) {
         return new SingleKey(base_1.hex.decode(privateKeyHex));
     }
+    static fromRandomBytes() {
+        return new SingleKey((0, utils_1.randomPrivateKeyBytes)());
+    }
+    /**
+     * Export the private key as a hex string.
+     *
+     * @returns The private key as a hex string
+     */
+    toHex() {
+        return base_1.hex.encode(this.key);
+    }
     async sign(tx, inputIndexes) {
         const txCpy = tx.clone();
         if (!inputIndexes) {
@@ -59,10 +74,14 @@ class SingleKey {
         return txCpy;
     }
     xOnlyPublicKey() {
-        return (0, utils_1.pubSchnorr)(this.key);
+        return Promise.resolve((0, utils_1.pubSchnorr)(this.key));
     }
     signerSession() {
         return signingSession_1.TreeSignerSession.random();
     }
+    async signMessage(message) {
+        const msgBytes = new TextEncoder().encode(message);
+        return secp256k1_1.schnorr.sign((0, utils_1.sha256)(msgBytes), this.key);
+    }
 }
 exports.SingleKey = SingleKey;

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Transaction = exports.Unroll = exports.P2A = exports.TxTree = exports.BIP322 = exports.IndexedDBVtxoRepository = exports.networks = exports.ArkNote = exports.waitForIncomingFunds = exports.buildOffchainTx = exports.ConditionWitness = exports.VtxoTaprootTree = exports.VtxoTreeExpiry = exports.CosignerPublicKey = exports.getArkPsbtFields = exports.setArkPsbtField = exports.ArkPsbtFieldKeyType = exports.ArkPsbtFieldKey = exports.CLTVMultisigTapscript = exports.ConditionMultisigTapscript = exports.ConditionCSVMultisigTapscript = exports.CSVMultisigTapscript = exports.MultisigTapscript = exports.decodeTapscript = exports.Response = exports.Request = exports.ServiceWorkerWallet = exports.Worker = exports.setupServiceWorker = exports.SettlementEventType = exports.ChainTxType = exports.IndexerTxType = exports.TxType = exports.VHTLC = exports.VtxoScript = exports.DefaultVtxo = exports.ArkAddress = exports.RestIndexerProvider = exports.RestArkProvider = exports.EsploraProvider = exports.ESPLORA_URL = exports.Ramps = exports.OnchainWallet = exports.SingleKey = exports.Wallet = void 0;
+exports.Transaction = exports.Unroll = exports.P2A = exports.TxTree = exports.BIP322 = exports.ContractRepositoryImpl = exports.WalletRepositoryImpl = exports.networks = exports.ArkNote = exports.waitForIncomingFunds = exports.buildOffchainTx = exports.ConditionWitness = exports.VtxoTaprootTree = exports.VtxoTreeExpiry = exports.CosignerPublicKey = exports.getArkPsbtFields = exports.setArkPsbtField = exports.ArkPsbtFieldKeyType = exports.ArkPsbtFieldKey = exports.CLTVMultisigTapscript = exports.ConditionMultisigTapscript = exports.ConditionCSVMultisigTapscript = exports.CSVMultisigTapscript = exports.MultisigTapscript = exports.decodeTapscript = exports.Response = exports.Request = exports.ServiceWorkerWallet = exports.Worker = exports.setupServiceWorker = exports.SettlementEventType = exports.ChainTxType = exports.IndexerTxType = exports.TxType = exports.VHTLC = exports.VtxoScript = exports.DefaultVtxo = exports.ArkAddress = exports.RestIndexerProvider = exports.RestArkProvider = exports.EsploraProvider = exports.ESPLORA_URL = exports.Ramps = exports.OnchainWallet = exports.SingleKey = exports.Wallet = void 0;
 const btc_signer_1 = require("@scure/btc-signer");
 Object.defineProperty(exports, "Transaction", { enumerable: true, get: function () { return btc_signer_1.Transaction; } });
 const singleKey_1 = require("./identity/singleKey");
@@ -62,8 +62,6 @@ const bip322_1 = require("./bip322");
 Object.defineProperty(exports, "BIP322", { enumerable: true, get: function () { return bip322_1.BIP322; } });
 const arknote_1 = require("./arknote");
 Object.defineProperty(exports, "ArkNote", { enumerable: true, get: function () { return arknote_1.ArkNote; } });
-const idb_1 = require("./wallet/serviceWorker/db/vtxo/idb");
-Object.defineProperty(exports, "IndexedDBVtxoRepository", { enumerable: true, get: function () { return idb_1.IndexedDBVtxoRepository; } });
 const networks_1 = require("./networks");
 Object.defineProperty(exports, "networks", { enumerable: true, get: function () { return networks_1.networks; } });
 const indexer_1 = require("./providers/indexer");
@@ -74,3 +72,7 @@ const anchor_1 = require("./utils/anchor");
 Object.defineProperty(exports, "P2A", { enumerable: true, get: function () { return anchor_1.P2A; } });
 const unroll_1 = require("./wallet/unroll");
 Object.defineProperty(exports, "Unroll", { enumerable: true, get: function () { return unroll_1.Unroll; } });
+const walletRepository_1 = require("./repositories/walletRepository");
+Object.defineProperty(exports, "WalletRepositoryImpl", { enumerable: true, get: function () { return walletRepository_1.WalletRepositoryImpl; } });
+const contractRepository_1 = require("./repositories/contractRepository");
+Object.defineProperty(exports, "ContractRepositoryImpl", { enumerable: true, get: function () { return contractRepository_1.ContractRepositoryImpl; } });

package/dist/cjs/musig2/keys.js

@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.aggregateKeys = aggregateKeys;
 const musig = __importStar(require("@scure/btc-signer/musig2"));
-const secp256k1_1 = require("@noble/curves/secp256k1");
+const secp256k1_js_1 = require("@noble/curves/secp256k1.js");
 // Aggregates multiple public keys according to the MuSig2 algorithm
 function aggregateKeys(publicKeys, sort, options = {}) {
     if (sort) {
@@ -44,14 +44,14 @@ function aggregateKeys(publicKeys, sort, options = {}) {
     const { aggPublicKey: preTweakedKey } = musig.keyAggregate(publicKeys);
     if (!options.taprootTweak) {
         return {
-            preTweakedKey: preTweakedKey.toRawBytes(true),
-            finalKey: preTweakedKey.toRawBytes(true),
+            preTweakedKey: preTweakedKey.toBytes(true),
+            finalKey: preTweakedKey.toBytes(true),
         };
     }
-    const tweakBytes = secp256k1_1.schnorr.utils.taggedHash("TapTweak", preTweakedKey.toRawBytes(true).subarray(1), options.taprootTweak ?? new Uint8Array(0));
+    const tweakBytes = secp256k1_js_1.schnorr.utils.taggedHash("TapTweak", preTweakedKey.toBytes(true).subarray(1), options.taprootTweak ?? new Uint8Array(0));
     const { aggPublicKey: finalKey } = musig.keyAggregate(publicKeys, [tweakBytes], [true]);
     return {
-        preTweakedKey: preTweakedKey.toRawBytes(true),
-        finalKey: finalKey.toRawBytes(true),
+        preTweakedKey: preTweakedKey.toBytes(true),
+        finalKey: finalKey.toBytes(true),
     };
 }

package/dist/cjs/musig2/sign.js

@@ -36,10 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PartialSig = exports.PartialSignatureError = void 0;
 exports.sign = sign;
 const musig = __importStar(require("@scure/btc-signer/musig2"));
-const utils_1 = require("@noble/curves/abstract/utils");
+const utils_js_1 = require("@noble/curves/utils.js");
 const secp256k1_1 = require("@noble/secp256k1");
 const keys_1 = require("./keys");
-const secp256k1_2 = require("@noble/curves/secp256k1");
+const secp256k1_js_1 = require("@noble/curves/secp256k1.js");
 // Add this error type for decode failures
 class PartialSignatureError extends Error {
     constructor(message) {
@@ -77,8 +77,8 @@ class PartialSig {
             throw new PartialSignatureError("Invalid partial signature length");
         }
         // Verify s is less than curve order
-        const s = (0, utils_1.bytesToNumberBE)(bytes);
-        if (s >= secp256k1_1.CURVE.n) {
+        const s = (0, utils_js_1.bytesToNumberBE)(bytes);
+        if (s >= secp256k1_1.Point.CURVE().n) {
             throw new PartialSignatureError("s value overflows curve order");
         }
         // For decode we don't have R, so we'll need to compute it later
@@ -94,7 +94,7 @@ function sign(secNonce, privateKey, combinedNonce, publicKeys, message, options)
     let tweakBytes;
     if (options?.taprootTweak !== undefined) {
         const { preTweakedKey } = (0, keys_1.aggregateKeys)(options?.sortKeys ? musig.sortKeys(publicKeys) : publicKeys, true);
-        tweakBytes = secp256k1_2.schnorr.utils.taggedHash("TapTweak", preTweakedKey.subarray(1), options.taprootTweak);
+        tweakBytes = secp256k1_js_1.schnorr.utils.taggedHash("TapTweak", preTweakedKey.subarray(1), options.taprootTweak);
     }
     const session = new musig.Session(combinedNonce, options?.sortKeys ? musig.sortKeys(publicKeys) : publicKeys, message, tweakBytes ? [tweakBytes] : undefined, tweakBytes ? [true] : undefined);
     const partialSig = session.sign(secNonce, privateKey);

package/dist/cjs/repositories/contractRepository.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContractRepositoryImpl = void 0;
+class ContractRepositoryImpl {
+    constructor(storage) {
+        this.cache = new Map();
+        this.storage = storage;
+    }
+    async getContractData(contractId, key) {
+        const storageKey = `contract:${contractId}:${key}`;
+        const cached = this.cache.get(storageKey);
+        if (cached !== undefined)
+            return cached;
+        const stored = await this.storage.getItem(storageKey);
+        if (!stored)
+            return null;
+        try {
+            const data = JSON.parse(stored);
+            this.cache.set(storageKey, data);
+            return data;
+        }
+        catch (error) {
+            console.error(`Failed to parse contract data for ${contractId}:${key}:`, error);
+            return null;
+        }
+    }
+    async setContractData(contractId, key, data) {
+        const storageKey = `contract:${contractId}:${key}`;
+        try {
+            // First persist to storage, only update cache if successful
+            await this.storage.setItem(storageKey, JSON.stringify(data));
+            this.cache.set(storageKey, data);
+        }
+        catch (error) {
+            // Storage operation failed, cache remains unchanged
+            console.error(`Failed to persist contract data for ${contractId}:${key}:`, error);
+            throw error; // Rethrow to notify caller of failure
+        }
+    }
+    async deleteContractData(contractId, key) {
+        const storageKey = `contract:${contractId}:${key}`;
+        try {
+            // First remove from persistent storage, only delete from cache if successful
+            await this.storage.removeItem(storageKey);
+            this.cache.delete(storageKey);
+        }
+        catch (error) {
+            // Storage operation failed, cache remains unchanged
+            console.error(`Failed to remove contract data for ${contractId}:${key}:`, error);
+            throw error; // Rethrow to notify caller of failure
+        }
+    }
+    async getContractCollection(contractType) {
+        const storageKey = `collection:${contractType}`;
+        const cached = this.cache.get(storageKey);
+        if (cached !== undefined)
+            return cached;
+        const stored = await this.storage.getItem(storageKey);
+        if (!stored) {
+            this.cache.set(storageKey, []);
+            return [];
+        }
+        try {
+            const collection = JSON.parse(stored);
+            this.cache.set(storageKey, collection);
+            return collection;
+        }
+        catch (error) {
+            console.error(`Failed to parse contract collection ${contractType}:`, error);
+            this.cache.set(storageKey, []);
+            return [];
+        }
+    }
+    async saveToContractCollection(contractType, item, idField) {
+        const collection = await this.getContractCollection(contractType);
+        // Validate that the item has the required id field
+        const itemId = item[idField];
+        if (itemId === undefined || itemId === null) {
+            throw new Error(`Item is missing required field '${String(idField)}'`);
+        }
+        // Find existing item index without mutating the original collection
+        const existingIndex = collection.findIndex((i) => i[idField] === itemId);
+        // Build new collection without mutating the cached one
+        let newCollection;
+        if (existingIndex !== -1) {
+            // Replace existing item
+            newCollection = [
+                ...collection.slice(0, existingIndex),
+                item,
+                ...collection.slice(existingIndex + 1),
+            ];
+        }
+        else {
+            // Add new item
+            newCollection = [...collection, item];
+        }
+        const storageKey = `collection:${contractType}`;
+        try {
+            // First persist to storage, only update cache if successful
+            await this.storage.setItem(storageKey, JSON.stringify(newCollection));
+            this.cache.set(storageKey, newCollection);
+        }
+        catch (error) {
+            // Storage operation failed, cache remains unchanged
+            console.error(`Failed to persist contract collection ${contractType}:`, error);
+            throw error; // Rethrow to notify caller of failure
+        }
+    }
+    async removeFromContractCollection(contractType, id, idField) {
+        // Validate input parameters
+        if (id === undefined || id === null) {
+            throw new Error(`Invalid id provided for removal: ${String(id)}`);
+        }
+        const collection = await this.getContractCollection(contractType);
+        // Build new collection without the specified item
+        const filtered = collection.filter((item) => item[idField] !== id);
+        const storageKey = `collection:${contractType}`;
+        try {
+            // First persist to storage, only update cache if successful
+            await this.storage.setItem(storageKey, JSON.stringify(filtered));
+            this.cache.set(storageKey, filtered);
+        }
+        catch (error) {
+            // Storage operation failed, cache remains unchanged
+            console.error(`Failed to persist contract collection removal for ${contractType}:`, error);
+            throw error; // Rethrow to notify caller of failure
+        }
+    }
+}
+exports.ContractRepositoryImpl = ContractRepositoryImpl;

package/dist/cjs/repositories/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./walletRepository"), exports);
+__exportStar(require("./contractRepository"), exports);