@unicitylabs/sphere-sdk 0.7.1-dev.3 → 0.7.1

package/dist/core/index.d.cts

@@ -4313,6 +4313,42 @@ declare class PaymentsModule {
      * @returns MintNametagResult with success status and token if successful
      */
     mintNametag(nametag: string): Promise<MintNametagResult>;
+    /**
+     * Mint a fungible token directly to this wallet (genesis mint).
+     *
+     * Useful for test setups that need to seed a wallet with specific token
+     * balances WITHOUT depending on the testnet faucet HTTP service. The
+     * resulting token has the canonical CoinId bytes (passed in `coinIdHex`)
+     * — when those bytes match a registered symbol in the TokenRegistry,
+     * the token shows up under the symbol's name (e.g. "UCT"). There is no
+     * cryptographic restriction on which key may issue a given CoinId; the
+     * aggregator records the mint regardless of issuer identity.
+     *
+     * The flow:
+     *   1. Generate a random TokenId.
+     *   2. Build TokenCoinData with [(coinId, amount)].
+     *   3. Build MintTransactionData with recipient = self (UnmaskedPredicate
+     *      from this wallet's signing service).
+     *   4. Submit MintCommitment to the aggregator.
+     *   5. Wait for the inclusion proof.
+     *   6. Construct an SDK Token via Token.mint().
+     *   7. Convert to wallet Token format and call addToken().
+     *
+     * @param coinIdHex - 64-char lowercase hex CoinId. Must match the bytes
+     *   used by the registered symbol if you want the wallet to recognize
+     *   the token as that symbol (e.g. UCT's coinId from the public registry).
+     * @param amount - Amount in smallest units (multiply by 10^decimals
+     *   when converting from human values).
+     * @returns Result with the resulting wallet Token and its on-chain id.
+     */
+    mintFungibleToken(coinIdHex: string, amount: bigint): Promise<{
+        success: true;
+        token: Token;
+        tokenId: string;
+    } | {
+        success: false;
+        error: string;
+    }>;
     /**
      * Check if a nametag is available for minting
      * @param nametag - The nametag to check (e.g., "alice" or "@alice")
@@ -4792,6 +4828,24 @@ declare class AccountingModule {
     private dirtyLedgerEntries;
     /** Count of unknown (not in invoiceTermsCache) invoice IDs in the ledger. */
     private unknownLedgerCount;
+    /**
+     * Per-unknown-invoice first-seen timestamp for TTL eviction.
+     *
+     * W1 (steelman round-4): without TTL, an attacker who can deliver 500
+     * inbound transfers with synthesized memo invoiceIds permanently exhausts
+     * the unknown-ledger cap, after which legitimate orphan transfers (out-of-
+     * order delivery for real swaps) are silently dropped at the cap-check.
+     *
+     * Round-5 perf: gated by `unknownLedgerNextSweepMs` to amortize the
+     * sweep cost. The naive every-call sweep is O(N) where N=cap=500;
+     * combined with the per-token cleanup loop inside the sweep it became
+     * O(N×M) on every transfer under flood. Now we sweep at most every
+     * `UNKNOWN_LEDGER_SWEEP_INTERVAL_MS` (60s) UNLESS the cap is currently
+     * full, in which case we sweep on each call (the only path that can
+     * actually drop a legitimate orphan).
+     */
+    private unknownLedgerFirstSeen;
+    private unknownLedgerNextSweepMs;
     /** W17: Tracks whether tokenScanState has been mutated since last flush. */
     private tokenScanDirty;
     /** W2 fix: Serialization guard for _flushDirtyLedgerEntries. */
@@ -4976,6 +5030,21 @@ declare class AccountingModule {
      * @throws {SphereError} `NOT_INITIALIZED` — module not initialized.
      */
     getInvoice(invoiceId: string): InvoiceRef | null;
+    /**
+     * Return the set of token IDs that are currently linked to the given
+     * invoice. Populated by both the on-chain `_processTokenTransactions`
+     * path (tokens with `inv:` references) and the transport-memo orphan
+     * buffering path in `_handleIncomingTransfer`.
+     *
+     * Used by callers that want to scope per-invoice operations (e.g.
+     * SwapModule.verifyPayout's L3 validation) to only the tokens that
+     * cover this invoice — avoiding false negatives when the wallet
+     * contains unrelated tokens of the same currency in unconfirmed or
+     * spent state.
+     *
+     * Returns an empty set if no tokens are currently linked.
+     */
+    getTokenIdsForInvoice(invoiceId: string): Set<string>;
     /**
      * Explicitly close an invoice. Only target parties may close (§8.3).
      *
@@ -5323,6 +5392,35 @@ declare class AccountingModule {
      * await and the null assignment, so we loop until the field is null.
      */
     private _drainFlushPromise;
+    /**
+     * Synchronously persist any pending provisional ledger entry for `invoiceId`
+     * before returning to the caller. Used by `payInvoice` and
+     * `returnInvoicePayment` to make the in-memory provisional entry durable
+     * inside the same per-invoice gate that wrote it, closing the
+     * crash-mid-conclude race that produces over-coverage on receivers.
+     *
+     * Implementation:
+     *   1. Schedule a flush via the existing `_flushPromise` chain (so
+     *      concurrent `_handleTokenChange` callers waiting on the chain
+     *      observe ours as part of the sequence).
+     *   2. Await OUR flush directly — NOT `_drainFlushPromise()`, which would
+     *      spin while concurrent token changes keep extending the chain and
+     *      hold the per-invoice gate for an unbounded number of additional
+     *      flushes. We only need OUR provisional entry durable.
+     *   3. `_flushDirtyLedgerEntries` swallows per-invoice `storage.set`
+     *      rejections internally (sets a local `step1Failed` flag), leaving
+     *      the dirty entry on the set without re-throwing. So we post-check
+     *      `dirtyLedgerEntries.has(invoiceId)` and throw a `STORAGE_ERROR`
+     *      `SphereError` if our entry is still dirty — propagating to the
+     *      caller so they learn about the durability failure rather than
+     *      receiving a silent "success" return that lies on disk.
+     *
+     * @param invoiceId    The invoice whose provisional entry must be durable.
+     * @param callContext  Used in the error message so the caller is named
+     *                     ('payInvoice' / 'returnInvoicePayment') without
+     *                     forcing a stack-trace inspection.
+     */
+    private _persistProvisionalAndVerify;
     /**
      * Handle an incoming transfer event from PaymentsModule (§6.2).
      *
@@ -6393,6 +6491,23 @@ type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
  */
 type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
 
+/**
+ * Compute the Unicity L3 DIRECT:// address that corresponds to a given
+ * compressed secp256k1 public key.
+ *
+ * Deterministic — the underlying primitive `UnmaskedPredicateReference.create`
+ * only uses the public key, so the private key is never needed. This lets
+ * a backend trust only one thing from the client (the chain pubkey, whose
+ * ownership the client proves via signature) and derive everything else
+ * locally. Closes the entire class of "client claims an identifier the
+ * server can't verify" bugs at the API level.
+ *
+ * @param chainPubkey 33-byte compressed secp256k1 pubkey, hex-encoded
+ *                    (66 chars, leading 02 or 03).
+ * @throws if chainPubkey doesn't match the compressed-secp256k1 format.
+ */
+declare function computeDirectAddressFromChainPubkey(chainPubkey: string): Promise<string>;
+
 declare function isValidNametag(nametag: string): boolean;
 
 /** Steps reported by the onProgress callback during wallet init/create/load/import */
@@ -6634,6 +6749,7 @@ interface SphereInitResult {
     /** Generated mnemonic (only if autoGenerate was used) */
     generatedMnemonic?: string;
 }
+
 /**
  * Holds all per-address module instances.
  * Each HD address gets its own set so modules can run independently in background.
@@ -7880,4 +7996,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeDirectAddressFromChainPubkey, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };

package/dist/core/index.d.ts

@@ -4313,6 +4313,42 @@ declare class PaymentsModule {
      * @returns MintNametagResult with success status and token if successful
      */
     mintNametag(nametag: string): Promise<MintNametagResult>;
+    /**
+     * Mint a fungible token directly to this wallet (genesis mint).
+     *
+     * Useful for test setups that need to seed a wallet with specific token
+     * balances WITHOUT depending on the testnet faucet HTTP service. The
+     * resulting token has the canonical CoinId bytes (passed in `coinIdHex`)
+     * — when those bytes match a registered symbol in the TokenRegistry,
+     * the token shows up under the symbol's name (e.g. "UCT"). There is no
+     * cryptographic restriction on which key may issue a given CoinId; the
+     * aggregator records the mint regardless of issuer identity.
+     *
+     * The flow:
+     *   1. Generate a random TokenId.
+     *   2. Build TokenCoinData with [(coinId, amount)].
+     *   3. Build MintTransactionData with recipient = self (UnmaskedPredicate
+     *      from this wallet's signing service).
+     *   4. Submit MintCommitment to the aggregator.
+     *   5. Wait for the inclusion proof.
+     *   6. Construct an SDK Token via Token.mint().
+     *   7. Convert to wallet Token format and call addToken().
+     *
+     * @param coinIdHex - 64-char lowercase hex CoinId. Must match the bytes
+     *   used by the registered symbol if you want the wallet to recognize
+     *   the token as that symbol (e.g. UCT's coinId from the public registry).
+     * @param amount - Amount in smallest units (multiply by 10^decimals
+     *   when converting from human values).
+     * @returns Result with the resulting wallet Token and its on-chain id.
+     */
+    mintFungibleToken(coinIdHex: string, amount: bigint): Promise<{
+        success: true;
+        token: Token;
+        tokenId: string;
+    } | {
+        success: false;
+        error: string;
+    }>;
     /**
      * Check if a nametag is available for minting
      * @param nametag - The nametag to check (e.g., "alice" or "@alice")
@@ -4792,6 +4828,24 @@ declare class AccountingModule {
     private dirtyLedgerEntries;
     /** Count of unknown (not in invoiceTermsCache) invoice IDs in the ledger. */
     private unknownLedgerCount;
+    /**
+     * Per-unknown-invoice first-seen timestamp for TTL eviction.
+     *
+     * W1 (steelman round-4): without TTL, an attacker who can deliver 500
+     * inbound transfers with synthesized memo invoiceIds permanently exhausts
+     * the unknown-ledger cap, after which legitimate orphan transfers (out-of-
+     * order delivery for real swaps) are silently dropped at the cap-check.
+     *
+     * Round-5 perf: gated by `unknownLedgerNextSweepMs` to amortize the
+     * sweep cost. The naive every-call sweep is O(N) where N=cap=500;
+     * combined with the per-token cleanup loop inside the sweep it became
+     * O(N×M) on every transfer under flood. Now we sweep at most every
+     * `UNKNOWN_LEDGER_SWEEP_INTERVAL_MS` (60s) UNLESS the cap is currently
+     * full, in which case we sweep on each call (the only path that can
+     * actually drop a legitimate orphan).
+     */
+    private unknownLedgerFirstSeen;
+    private unknownLedgerNextSweepMs;
     /** W17: Tracks whether tokenScanState has been mutated since last flush. */
     private tokenScanDirty;
     /** W2 fix: Serialization guard for _flushDirtyLedgerEntries. */
@@ -4976,6 +5030,21 @@ declare class AccountingModule {
      * @throws {SphereError} `NOT_INITIALIZED` — module not initialized.
      */
     getInvoice(invoiceId: string): InvoiceRef | null;
+    /**
+     * Return the set of token IDs that are currently linked to the given
+     * invoice. Populated by both the on-chain `_processTokenTransactions`
+     * path (tokens with `inv:` references) and the transport-memo orphan
+     * buffering path in `_handleIncomingTransfer`.
+     *
+     * Used by callers that want to scope per-invoice operations (e.g.
+     * SwapModule.verifyPayout's L3 validation) to only the tokens that
+     * cover this invoice — avoiding false negatives when the wallet
+     * contains unrelated tokens of the same currency in unconfirmed or
+     * spent state.
+     *
+     * Returns an empty set if no tokens are currently linked.
+     */
+    getTokenIdsForInvoice(invoiceId: string): Set<string>;
     /**
      * Explicitly close an invoice. Only target parties may close (§8.3).
      *
@@ -5323,6 +5392,35 @@ declare class AccountingModule {
      * await and the null assignment, so we loop until the field is null.
      */
     private _drainFlushPromise;
+    /**
+     * Synchronously persist any pending provisional ledger entry for `invoiceId`
+     * before returning to the caller. Used by `payInvoice` and
+     * `returnInvoicePayment` to make the in-memory provisional entry durable
+     * inside the same per-invoice gate that wrote it, closing the
+     * crash-mid-conclude race that produces over-coverage on receivers.
+     *
+     * Implementation:
+     *   1. Schedule a flush via the existing `_flushPromise` chain (so
+     *      concurrent `_handleTokenChange` callers waiting on the chain
+     *      observe ours as part of the sequence).
+     *   2. Await OUR flush directly — NOT `_drainFlushPromise()`, which would
+     *      spin while concurrent token changes keep extending the chain and
+     *      hold the per-invoice gate for an unbounded number of additional
+     *      flushes. We only need OUR provisional entry durable.
+     *   3. `_flushDirtyLedgerEntries` swallows per-invoice `storage.set`
+     *      rejections internally (sets a local `step1Failed` flag), leaving
+     *      the dirty entry on the set without re-throwing. So we post-check
+     *      `dirtyLedgerEntries.has(invoiceId)` and throw a `STORAGE_ERROR`
+     *      `SphereError` if our entry is still dirty — propagating to the
+     *      caller so they learn about the durability failure rather than
+     *      receiving a silent "success" return that lies on disk.
+     *
+     * @param invoiceId    The invoice whose provisional entry must be durable.
+     * @param callContext  Used in the error message so the caller is named
+     *                     ('payInvoice' / 'returnInvoicePayment') without
+     *                     forcing a stack-trace inspection.
+     */
+    private _persistProvisionalAndVerify;
     /**
      * Handle an incoming transfer event from PaymentsModule (§6.2).
      *
@@ -6393,6 +6491,23 @@ type LegacyFileType = 'dat' | 'txt' | 'json' | 'mnemonic' | 'unknown';
  */
 type DecryptionProgressCallback = (iteration: number, total: number) => Promise<void> | void;
 
+/**
+ * Compute the Unicity L3 DIRECT:// address that corresponds to a given
+ * compressed secp256k1 public key.
+ *
+ * Deterministic — the underlying primitive `UnmaskedPredicateReference.create`
+ * only uses the public key, so the private key is never needed. This lets
+ * a backend trust only one thing from the client (the chain pubkey, whose
+ * ownership the client proves via signature) and derive everything else
+ * locally. Closes the entire class of "client claims an identifier the
+ * server can't verify" bugs at the API level.
+ *
+ * @param chainPubkey 33-byte compressed secp256k1 pubkey, hex-encoded
+ *                    (66 chars, leading 02 or 03).
+ * @throws if chainPubkey doesn't match the compressed-secp256k1 format.
+ */
+declare function computeDirectAddressFromChainPubkey(chainPubkey: string): Promise<string>;
+
 declare function isValidNametag(nametag: string): boolean;
 
 /** Steps reported by the onProgress callback during wallet init/create/load/import */
@@ -6634,6 +6749,7 @@ interface SphereInitResult {
     /** Generated mnemonic (only if autoGenerate was used) */
     generatedMnemonic?: string;
 }
+
 /**
  * Holds all per-address module instances.
  * Each HD address gets its own set so modules can run independently in background.
@@ -7880,4 +7996,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeDirectAddressFromChainPubkey, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };