@unicitylabs/sphere-sdk 0.17.2 → 0.17.3

package/dist/core/index.d.cts

@@ -445,7 +445,7 @@ interface PaymentsV2 {
  * }
  * ```
  */
-type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'TRANSFER_CONFLICT' | 'CERTIFICATION_UNCONFIRMED' | 'CHECKPOINT_PERSIST_FAILED' | 'SPLIT_CHECKPOINT_LOST' | 'CHECKPOINT_TRUSTBASE_MISMATCH' | 'STORAGE_ERROR' | 'SEND_SYNC_PENDING' | 'SEND_PARTIALLY_COMPLETED' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'INVALID_AMOUNT' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'SIGNING_ERROR' | 'SEND_QUEUE_TIMEOUT' | 'SEND_INSUFFICIENT_BALANCE' | 'SEND_RESERVATION_CANCELLED' | 'SEND_QUEUE_FULL' | 'MODULE_DESTROYED' | 'REENTRANT_GATE' | 'INVOICE_NO_TARGETS' | 'INVOICE_INVALID_ADDRESS' | 'INVOICE_NO_ASSETS' | 'INVOICE_INVALID_ASSET' | 'INVOICE_INVALID_AMOUNT' | 'INVOICE_INVALID_COIN' | 'INVOICE_INVALID_NFT' | 'INVOICE_PAST_DUE_DATE' | 'INVOICE_DUPLICATE_ADDRESS' | 'INVOICE_DUPLICATE_COIN' | 'INVOICE_DUPLICATE_NFT' | 'INVOICE_MINT_FAILED' | 'INVOICE_INVALID_PROOF' | 'INVOICE_WRONG_TOKEN_TYPE' | 'INVOICE_INVALID_DATA' | 'INVOICE_ALREADY_EXISTS' | 'INVOICE_NOT_FOUND' | 'INVOICE_NOT_TARGET' | 'INVOICE_ALREADY_CLOSED' | 'INVOICE_ALREADY_CANCELLED' | 'INVOICE_ORACLE_REQUIRED' | 'INVOICE_TERMINATED' | 'INVOICE_INVALID_TARGET' | 'INVOICE_INVALID_ASSET_INDEX' | 'INVOICE_RETURN_EXCEEDS_BALANCE' | 'INVOICE_INVALID_DELIVERY_METHOD' | 'INVOICE_INVALID_REFUND_ADDRESS' | 'INVOICE_INVALID_CONTACT' | 'INVOICE_INVALID_ID' | 'INVOICE_TOO_MANY_TARGETS' | 'INVOICE_TOO_MANY_ASSETS' | 'INVOICE_MEMO_TOO_LONG' | 'INVOICE_TERMS_TOO_LARGE' | 'INVOICE_NOT_TERMINATED' | 'INVOICE_NOT_CANCELLED' | 'INVOICE_STORAGE_FAILED' | 'RATE_LIMITED' | 'COMMUNICATIONS_UNAVAILABLE' | 'SWAP_INVALID_DEAL' | 'SWAP_INVALID_MANIFEST' | 'SWAP_NOT_FOUND' | 'SWAP_WRONG_STATE' | 'SWAP_RESOLVE_FAILED' | 'SWAP_DM_SEND_FAILED' | 'SWAP_ESCROW_REJECTED' | 'SWAP_DEPOSIT_FAILED' | 'SWAP_PAYOUT_VERIFICATION_FAILED' | 'SWAP_ALREADY_EXISTS' | 'SWAP_ALREADY_COMPLETED' | 'SWAP_ALREADY_CANCELLED' | 'SWAP_TIMEOUT' | 'SWAP_LIMIT_EXCEEDED' | 'SWAP_ALREADY_INITIALIZED' | 'SWAP_MODULE_DESTROYED' | 'SWAP_NOT_INITIALIZED';
+type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'TRANSFER_CONFLICT' | 'CERTIFICATION_UNCONFIRMED' | 'CHECKPOINT_PERSIST_FAILED' | 'SPLIT_CHECKPOINT_LOST' | 'CHECKPOINT_TRUSTBASE_MISMATCH' | 'STORAGE_ERROR' | 'SEND_SYNC_PENDING' | 'SEND_PARTIALLY_COMPLETED' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'INVALID_AMOUNT' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'PAYMENTS_NOT_COMPOSED' | 'SIGNING_ERROR' | 'SEND_QUEUE_TIMEOUT' | 'SEND_INSUFFICIENT_BALANCE' | 'SEND_RESERVATION_CANCELLED' | 'SEND_QUEUE_FULL' | 'MODULE_DESTROYED' | 'REENTRANT_GATE' | 'INVOICE_NO_TARGETS' | 'INVOICE_INVALID_ADDRESS' | 'INVOICE_NO_ASSETS' | 'INVOICE_INVALID_ASSET' | 'INVOICE_INVALID_AMOUNT' | 'INVOICE_INVALID_COIN' | 'INVOICE_INVALID_NFT' | 'INVOICE_PAST_DUE_DATE' | 'INVOICE_DUPLICATE_ADDRESS' | 'INVOICE_DUPLICATE_COIN' | 'INVOICE_DUPLICATE_NFT' | 'INVOICE_MINT_FAILED' | 'INVOICE_INVALID_PROOF' | 'INVOICE_WRONG_TOKEN_TYPE' | 'INVOICE_INVALID_DATA' | 'INVOICE_ALREADY_EXISTS' | 'INVOICE_NOT_FOUND' | 'INVOICE_NOT_TARGET' | 'INVOICE_ALREADY_CLOSED' | 'INVOICE_ALREADY_CANCELLED' | 'INVOICE_ORACLE_REQUIRED' | 'INVOICE_TERMINATED' | 'INVOICE_INVALID_TARGET' | 'INVOICE_INVALID_ASSET_INDEX' | 'INVOICE_RETURN_EXCEEDS_BALANCE' | 'INVOICE_INVALID_DELIVERY_METHOD' | 'INVOICE_INVALID_REFUND_ADDRESS' | 'INVOICE_INVALID_CONTACT' | 'INVOICE_INVALID_ID' | 'INVOICE_TOO_MANY_TARGETS' | 'INVOICE_TOO_MANY_ASSETS' | 'INVOICE_MEMO_TOO_LONG' | 'INVOICE_TERMS_TOO_LARGE' | 'INVOICE_NOT_TERMINATED' | 'INVOICE_NOT_CANCELLED' | 'INVOICE_STORAGE_FAILED' | 'RATE_LIMITED' | 'COMMUNICATIONS_UNAVAILABLE' | 'SWAP_INVALID_DEAL' | 'SWAP_INVALID_MANIFEST' | 'SWAP_NOT_FOUND' | 'SWAP_WRONG_STATE' | 'SWAP_RESOLVE_FAILED' | 'SWAP_DM_SEND_FAILED' | 'SWAP_ESCROW_REJECTED' | 'SWAP_DEPOSIT_FAILED' | 'SWAP_PAYOUT_VERIFICATION_FAILED' | 'SWAP_ALREADY_EXISTS' | 'SWAP_ALREADY_COMPLETED' | 'SWAP_ALREADY_CANCELLED' | 'SWAP_TIMEOUT' | 'SWAP_LIMIT_EXCEEDED' | 'SWAP_ALREADY_INITIALIZED' | 'SWAP_MODULE_DESTROYED' | 'SWAP_NOT_INITIALIZED';
 declare class SphereError extends Error {
     readonly code: SphereErrorCode;
     readonly cause?: unknown;
@@ -3165,6 +3165,9 @@ interface WalletApiTransportConfig {
     /** DI seam: supply the whole per-address bundle (offline tests, custom hosts). */
     paymentsV2Transport?(args: PaymentsV2TransportArgs): PaymentsV2Transport;
 }
+/** The messaging-only opt-out (#793) — sharing the `walletApi` field is what makes "configured" and "deliberately absent" mutually exclusive. */
+declare const NO_PAYMENTS = "none";
+type WalletApiOption = WalletApiTransportConfig | typeof NO_PAYMENTS;
 
 /**
  * Text Wallet Backup Serialization Types
@@ -3234,14 +3237,17 @@ interface InitProgress {
 /** Callback for tracking wallet initialization progress */
 type InitProgressCallback = (progress: InitProgress) => void;
 /**
- * The wallet-api transport config every wallet needs (money moves only through
- * the wallet-api vertical): `{ network, baseUrl, deviceId?, ... }` —
- * `createWalletApiProviders` (impl/shared/wallet-api) builds it. Shared by all
- * four init-option shapes below.
+ * The wallet-api transport config every wallet that moves money needs:
+ * `{ network, baseUrl, deviceId?, ... }` — `createWalletApiProviders`
+ * (impl/shared/wallet-api) builds it. Shared by all four init-option shapes below.
  */
 interface SphereWalletApiOptions {
-    /** Wallet-api transport config — REQUIRED (init throws INVALID_CONFIG without it). */
-    walletApi?: WalletApiTransportConfig;
+    /**
+     * Wallet-api transport config — REQUIRED, with one explicit escape: `'none'`
+     * composes no money at all (#793). Omitting the field still throws INVALID_CONFIG:
+     * "I forgot it" must never read the same as "I meant it".
+     */
+    walletApi?: WalletApiOption;
     /** @deprecated REMOVED with the P11 flip — any truthy value throws INVALID_CONFIG (invoicing no longer exists in the SDK). */
     accounting?: unknown;
     /** @deprecated REMOVED with the P11 flip — any truthy value throws INVALID_CONFIG (swaps no longer exist in the SDK). */
@@ -3530,7 +3536,11 @@ declare class Sphere {
     private _market;
     /** The ACTIVE address's running vertical — §7: exactly one at a time, ever. */
     private _paymentsV2Active;
-    /** Resolved wallet-api transport composition (network + per-address factory); set at init, fail-closed. */
+    /**
+     * Money composition, set at init. `null` = never resolved (a construction bug),
+     * `NO_PAYMENTS` = the explicit #793 opt-out, an object = a real composition. One
+     * spelling for the last two would read a forgotten resolve as messaging-only.
+     */
     private _paymentsV2Composition;
     /**
      * §7 lifecycle mutex: every stop/start pair runs strictly serialized, so
@@ -3717,6 +3727,12 @@ declare class Sphere {
     static generateMnemonic(strength?: 128 | 256): string;
     /** Payments (the §4 facade — the active address's running vertical). */
     get payments(): PaymentsV2;
+    /**
+     * Whether this Sphere composes money at all (#793) — fixed for the instance's life,
+     * so a messaging-only wallet can branch without a try/catch. Not a liveness check:
+     * `true` still leaves `payments` throwing NOT_INITIALIZED mid-init or mid-switch.
+     */
+    get hasPayments(): boolean;
     /** Communications module */
     get communications(): CommunicationsModule;
     /** Group chat module (NIP-29). Null if not configured. */
@@ -4891,4 +4907,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, type AddressModuleSet, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, DELIVERY_ENCRYPTION_HKDF_INFO, type DeliveryBundle, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, PartialSendConflictError, SIGN_MESSAGE_PREFIX, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type WalletApiTransportConfig, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, createKeyPair, createSphere, decrypt, decryptDeliveryBundle, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveDeliveryEncryptionKey, deriveFieldEncryptionKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, encrypt, encryptDeliveryBundle, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getPublicKey, hash160, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isPossiblyCommittedSendOutcome, isSphereError, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, parseTokenAmount, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, DELIVERY_ENCRYPTION_HKDF_INFO, type DeliveryBundle, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, NO_PAYMENTS, PartialSendConflictError, SIGN_MESSAGE_PREFIX, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type WalletApiOption, type WalletApiTransportConfig, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, createKeyPair, createSphere, decrypt, decryptDeliveryBundle, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveDeliveryEncryptionKey, deriveFieldEncryptionKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, encrypt, encryptDeliveryBundle, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getPublicKey, hash160, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isPossiblyCommittedSendOutcome, isSphereError, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, parseTokenAmount, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifySignedMessage };

package/dist/core/index.d.ts

@@ -445,7 +445,7 @@ interface PaymentsV2 {
  * }
  * ```
  */
-type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'TRANSFER_CONFLICT' | 'CERTIFICATION_UNCONFIRMED' | 'CHECKPOINT_PERSIST_FAILED' | 'SPLIT_CHECKPOINT_LOST' | 'CHECKPOINT_TRUSTBASE_MISMATCH' | 'STORAGE_ERROR' | 'SEND_SYNC_PENDING' | 'SEND_PARTIALLY_COMPLETED' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'INVALID_AMOUNT' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'SIGNING_ERROR' | 'SEND_QUEUE_TIMEOUT' | 'SEND_INSUFFICIENT_BALANCE' | 'SEND_RESERVATION_CANCELLED' | 'SEND_QUEUE_FULL' | 'MODULE_DESTROYED' | 'REENTRANT_GATE' | 'INVOICE_NO_TARGETS' | 'INVOICE_INVALID_ADDRESS' | 'INVOICE_NO_ASSETS' | 'INVOICE_INVALID_ASSET' | 'INVOICE_INVALID_AMOUNT' | 'INVOICE_INVALID_COIN' | 'INVOICE_INVALID_NFT' | 'INVOICE_PAST_DUE_DATE' | 'INVOICE_DUPLICATE_ADDRESS' | 'INVOICE_DUPLICATE_COIN' | 'INVOICE_DUPLICATE_NFT' | 'INVOICE_MINT_FAILED' | 'INVOICE_INVALID_PROOF' | 'INVOICE_WRONG_TOKEN_TYPE' | 'INVOICE_INVALID_DATA' | 'INVOICE_ALREADY_EXISTS' | 'INVOICE_NOT_FOUND' | 'INVOICE_NOT_TARGET' | 'INVOICE_ALREADY_CLOSED' | 'INVOICE_ALREADY_CANCELLED' | 'INVOICE_ORACLE_REQUIRED' | 'INVOICE_TERMINATED' | 'INVOICE_INVALID_TARGET' | 'INVOICE_INVALID_ASSET_INDEX' | 'INVOICE_RETURN_EXCEEDS_BALANCE' | 'INVOICE_INVALID_DELIVERY_METHOD' | 'INVOICE_INVALID_REFUND_ADDRESS' | 'INVOICE_INVALID_CONTACT' | 'INVOICE_INVALID_ID' | 'INVOICE_TOO_MANY_TARGETS' | 'INVOICE_TOO_MANY_ASSETS' | 'INVOICE_MEMO_TOO_LONG' | 'INVOICE_TERMS_TOO_LARGE' | 'INVOICE_NOT_TERMINATED' | 'INVOICE_NOT_CANCELLED' | 'INVOICE_STORAGE_FAILED' | 'RATE_LIMITED' | 'COMMUNICATIONS_UNAVAILABLE' | 'SWAP_INVALID_DEAL' | 'SWAP_INVALID_MANIFEST' | 'SWAP_NOT_FOUND' | 'SWAP_WRONG_STATE' | 'SWAP_RESOLVE_FAILED' | 'SWAP_DM_SEND_FAILED' | 'SWAP_ESCROW_REJECTED' | 'SWAP_DEPOSIT_FAILED' | 'SWAP_PAYOUT_VERIFICATION_FAILED' | 'SWAP_ALREADY_EXISTS' | 'SWAP_ALREADY_COMPLETED' | 'SWAP_ALREADY_CANCELLED' | 'SWAP_TIMEOUT' | 'SWAP_LIMIT_EXCEEDED' | 'SWAP_ALREADY_INITIALIZED' | 'SWAP_MODULE_DESTROYED' | 'SWAP_NOT_INITIALIZED';
+type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'TRANSFER_CONFLICT' | 'CERTIFICATION_UNCONFIRMED' | 'CHECKPOINT_PERSIST_FAILED' | 'SPLIT_CHECKPOINT_LOST' | 'CHECKPOINT_TRUSTBASE_MISMATCH' | 'STORAGE_ERROR' | 'SEND_SYNC_PENDING' | 'SEND_PARTIALLY_COMPLETED' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'INVALID_AMOUNT' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'PAYMENTS_NOT_COMPOSED' | 'SIGNING_ERROR' | 'SEND_QUEUE_TIMEOUT' | 'SEND_INSUFFICIENT_BALANCE' | 'SEND_RESERVATION_CANCELLED' | 'SEND_QUEUE_FULL' | 'MODULE_DESTROYED' | 'REENTRANT_GATE' | 'INVOICE_NO_TARGETS' | 'INVOICE_INVALID_ADDRESS' | 'INVOICE_NO_ASSETS' | 'INVOICE_INVALID_ASSET' | 'INVOICE_INVALID_AMOUNT' | 'INVOICE_INVALID_COIN' | 'INVOICE_INVALID_NFT' | 'INVOICE_PAST_DUE_DATE' | 'INVOICE_DUPLICATE_ADDRESS' | 'INVOICE_DUPLICATE_COIN' | 'INVOICE_DUPLICATE_NFT' | 'INVOICE_MINT_FAILED' | 'INVOICE_INVALID_PROOF' | 'INVOICE_WRONG_TOKEN_TYPE' | 'INVOICE_INVALID_DATA' | 'INVOICE_ALREADY_EXISTS' | 'INVOICE_NOT_FOUND' | 'INVOICE_NOT_TARGET' | 'INVOICE_ALREADY_CLOSED' | 'INVOICE_ALREADY_CANCELLED' | 'INVOICE_ORACLE_REQUIRED' | 'INVOICE_TERMINATED' | 'INVOICE_INVALID_TARGET' | 'INVOICE_INVALID_ASSET_INDEX' | 'INVOICE_RETURN_EXCEEDS_BALANCE' | 'INVOICE_INVALID_DELIVERY_METHOD' | 'INVOICE_INVALID_REFUND_ADDRESS' | 'INVOICE_INVALID_CONTACT' | 'INVOICE_INVALID_ID' | 'INVOICE_TOO_MANY_TARGETS' | 'INVOICE_TOO_MANY_ASSETS' | 'INVOICE_MEMO_TOO_LONG' | 'INVOICE_TERMS_TOO_LARGE' | 'INVOICE_NOT_TERMINATED' | 'INVOICE_NOT_CANCELLED' | 'INVOICE_STORAGE_FAILED' | 'RATE_LIMITED' | 'COMMUNICATIONS_UNAVAILABLE' | 'SWAP_INVALID_DEAL' | 'SWAP_INVALID_MANIFEST' | 'SWAP_NOT_FOUND' | 'SWAP_WRONG_STATE' | 'SWAP_RESOLVE_FAILED' | 'SWAP_DM_SEND_FAILED' | 'SWAP_ESCROW_REJECTED' | 'SWAP_DEPOSIT_FAILED' | 'SWAP_PAYOUT_VERIFICATION_FAILED' | 'SWAP_ALREADY_EXISTS' | 'SWAP_ALREADY_COMPLETED' | 'SWAP_ALREADY_CANCELLED' | 'SWAP_TIMEOUT' | 'SWAP_LIMIT_EXCEEDED' | 'SWAP_ALREADY_INITIALIZED' | 'SWAP_MODULE_DESTROYED' | 'SWAP_NOT_INITIALIZED';
 declare class SphereError extends Error {
     readonly code: SphereErrorCode;
     readonly cause?: unknown;
@@ -3165,6 +3165,9 @@ interface WalletApiTransportConfig {
     /** DI seam: supply the whole per-address bundle (offline tests, custom hosts). */
     paymentsV2Transport?(args: PaymentsV2TransportArgs): PaymentsV2Transport;
 }
+/** The messaging-only opt-out (#793) — sharing the `walletApi` field is what makes "configured" and "deliberately absent" mutually exclusive. */
+declare const NO_PAYMENTS = "none";
+type WalletApiOption = WalletApiTransportConfig | typeof NO_PAYMENTS;
 
 /**
  * Text Wallet Backup Serialization Types
@@ -3234,14 +3237,17 @@ interface InitProgress {
 /** Callback for tracking wallet initialization progress */
 type InitProgressCallback = (progress: InitProgress) => void;
 /**
- * The wallet-api transport config every wallet needs (money moves only through
- * the wallet-api vertical): `{ network, baseUrl, deviceId?, ... }` —
- * `createWalletApiProviders` (impl/shared/wallet-api) builds it. Shared by all
- * four init-option shapes below.
+ * The wallet-api transport config every wallet that moves money needs:
+ * `{ network, baseUrl, deviceId?, ... }` — `createWalletApiProviders`
+ * (impl/shared/wallet-api) builds it. Shared by all four init-option shapes below.
  */
 interface SphereWalletApiOptions {
-    /** Wallet-api transport config — REQUIRED (init throws INVALID_CONFIG without it). */
-    walletApi?: WalletApiTransportConfig;
+    /**
+     * Wallet-api transport config — REQUIRED, with one explicit escape: `'none'`
+     * composes no money at all (#793). Omitting the field still throws INVALID_CONFIG:
+     * "I forgot it" must never read the same as "I meant it".
+     */
+    walletApi?: WalletApiOption;
     /** @deprecated REMOVED with the P11 flip — any truthy value throws INVALID_CONFIG (invoicing no longer exists in the SDK). */
     accounting?: unknown;
     /** @deprecated REMOVED with the P11 flip — any truthy value throws INVALID_CONFIG (swaps no longer exist in the SDK). */
@@ -3530,7 +3536,11 @@ declare class Sphere {
     private _market;
     /** The ACTIVE address's running vertical — §7: exactly one at a time, ever. */
     private _paymentsV2Active;
-    /** Resolved wallet-api transport composition (network + per-address factory); set at init, fail-closed. */
+    /**
+     * Money composition, set at init. `null` = never resolved (a construction bug),
+     * `NO_PAYMENTS` = the explicit #793 opt-out, an object = a real composition. One
+     * spelling for the last two would read a forgotten resolve as messaging-only.
+     */
     private _paymentsV2Composition;
     /**
      * §7 lifecycle mutex: every stop/start pair runs strictly serialized, so
@@ -3717,6 +3727,12 @@ declare class Sphere {
     static generateMnemonic(strength?: 128 | 256): string;
     /** Payments (the §4 facade — the active address's running vertical). */
     get payments(): PaymentsV2;
+    /**
+     * Whether this Sphere composes money at all (#793) — fixed for the instance's life,
+     * so a messaging-only wallet can branch without a try/catch. Not a liveness check:
+     * `true` still leaves `payments` throwing NOT_INITIALIZED mid-init or mid-switch.
+     */
+    get hasPayments(): boolean;
     /** Communications module */
     get communications(): CommunicationsModule;
     /** Group chat module (NIP-29). Null if not configured. */
@@ -4891,4 +4907,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, type AddressModuleSet, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, DELIVERY_ENCRYPTION_HKDF_INFO, type DeliveryBundle, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, PartialSendConflictError, SIGN_MESSAGE_PREFIX, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type WalletApiTransportConfig, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, createKeyPair, createSphere, decrypt, decryptDeliveryBundle, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveDeliveryEncryptionKey, deriveFieldEncryptionKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, encrypt, encryptDeliveryBundle, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getPublicKey, hash160, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isPossiblyCommittedSendOutcome, isSphereError, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, parseTokenAmount, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, DELIVERY_ENCRYPTION_HKDF_INFO, type DeliveryBundle, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, NO_PAYMENTS, PartialSendConflictError, SIGN_MESSAGE_PREFIX, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type WalletApiOption, type WalletApiTransportConfig, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, createKeyPair, createSphere, decrypt, decryptDeliveryBundle, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveDeliveryEncryptionKey, deriveFieldEncryptionKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, encrypt, encryptDeliveryBundle, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getPublicKey, hash160, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isPossiblyCommittedSendOutcome, isSphereError, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, parseTokenAmount, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifySignedMessage };

package/dist/core/index.js

@@ -16976,7 +16976,16 @@ var WalletApiSplitCheckpointStore = class {
 };
 
 // core/payments-v2-wiring.ts
+var NO_PAYMENTS = "none";
+function readPaymentsOptOut(walletApi) {
+  if (walletApi === NO_PAYMENTS) return NO_PAYMENTS;
+  throw new SphereError(
+    `walletApi must be a wallet-api transport config or the literal '${NO_PAYMENTS}' (the explicit messaging-only opt-out, #793) \u2014 received ${JSON.stringify(walletApi)}.`,
+    "INVALID_CONFIG"
+  );
+}
 function resolvePaymentsV2Composition(walletApi, sphereNetwork) {
+  if (typeof walletApi === "string") return readPaymentsOptOut(walletApi);
   const source = walletApi;
   const network = typeof source?.network === "string" && source.network !== "" ? source.network : null;
   if (!source || network === null) {
@@ -17256,7 +17265,11 @@ var Sphere = class _Sphere {
   // The payments vertical (the ONLY money path since the P11 flip)
   /** The ACTIVE address's running vertical — §7: exactly one at a time, ever. */
   _paymentsV2Active = null;
-  /** Resolved wallet-api transport composition (network + per-address factory); set at init, fail-closed. */
+  /**
+   * Money composition, set at init. `null` = never resolved (a construction bug),
+   * `NO_PAYMENTS` = the explicit #793 opt-out, an object = a real composition. One
+   * spelling for the last two would read a forgotten resolve as messaging-only.
+   */
   _paymentsV2Composition = null;
   /**
    * §7 lifecycle mutex: every stop/start pair runs strictly serialized, so
@@ -17932,10 +17945,24 @@ var Sphere = class _Sphere {
   get payments() {
     const facade = this._paymentsV2Active?.facade;
     if (!facade) {
+      if (this._paymentsV2Composition === NO_PAYMENTS) {
+        throw new SphereError(
+          "payments is not composed: this Sphere was initialised with `walletApi: 'none'`, the explicit messaging-only composition. Money has no path here \u2014 re-init with a wallet-api transport config to move any.",
+          "PAYMENTS_NOT_COMPOSED"
+        );
+      }
       throw new SphereError("Sphere not initialized", "NOT_INITIALIZED");
     }
     return facade;
   }
+  /**
+   * Whether this Sphere composes money at all (#793) — fixed for the instance's life,
+   * so a messaging-only wallet can branch without a try/catch. Not a liveness check:
+   * `true` still leaves `payments` throwing NOT_INITIALIZED mid-init or mid-switch.
+   */
+  get hasPayments() {
+    return this._paymentsV2Composition !== NO_PAYMENTS;
+  }
   /** Communications module */
   get communications() {
     this.ensureReady();
@@ -19963,6 +19990,7 @@ var Sphere = class _Sphere {
    * breaks initialization.
    */
   async buildTokenEngine(identity) {
+    if (this._paymentsV2Composition === NO_PAYMENTS) return void 0;
     const oracle = this._oracle;
     const privateKey = (identity ?? this._identity)?.privateKey;
     const trustBaseJson = oracle.getTrustBaseJson?.() ?? null;
@@ -20068,6 +20096,7 @@ var Sphere = class _Sphere {
    * setOracleApiKey rebuild is what future operations snapshot.
    */
   async startPaymentsV2Inner(index, identity) {
+    if (this._paymentsV2Composition === NO_PAYMENTS) return;
     if (!this._paymentsV2Composition) {
       throw new SphereError("wallet-api composition required for money", "INVALID_CONFIG");
     }
@@ -20447,6 +20476,7 @@ export {
   FIELD_ENVELOPE_MAX_BYTES,
   FIELD_ENVELOPE_NONCE_BYTES,
   FIELD_ENVELOPE_PREFIX,
+  NO_PAYMENTS,
   PartialSendConflictError,
   SIGN_MESSAGE_PREFIX,
   Sphere,