@unicitylabs/sphere-sdk 0.16.0-dev.2 → 0.17.0

package/dist/modules/payments-v2/index.d.cts

@@ -56,6 +56,31 @@ interface Token {
      */
     suspectedSpent?: boolean;
 }
+/**
+ * A holding that names no coin (wallet-api#140) — an NFT. Deliberately NOT a
+ * `Token`: no amount, decimals or symbol, and never returned by `tokens()` or
+ * counted in `assets()`. `tokenType` names the token's CLASS and `tokenId` the
+ * instance (wallet-api#147). The payload is read with `payments.tokenData()`.
+ */
+interface CoinlessToken {
+    readonly tokenId: string;
+    readonly tokenType?: string;
+    /**
+     * Class metadata resolved from the registry THIS wallet owns, when the type is
+     * recognised. Resolved here so callers never reach for a registry themselves:
+     * the process-global singleton is repointable by another Sphere's init, so a
+     * second wallet on another network would retarget it (#767).
+     */
+    readonly name?: string;
+    readonly iconUrl?: string;
+    readonly stateHash: string;
+    /** #737: reserved by a converging transfer — not spendable right now. */
+    readonly transferring: boolean;
+    /** #625: proven spent on-chain; excluded from spend selection. */
+    readonly suspectedSpent?: boolean;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
 interface Asset {
     readonly coinId: string;
     readonly symbol: string;
@@ -126,6 +151,8 @@ interface IncomingTransfer {
     readonly senderPubkey: string;
     readonly senderNametag?: string;
     readonly tokens: Token[];
+    /** Arrivals that name no coin (#777). Disjoint from `tokens`, never a zero Token. */
+    readonly coinless?: CoinlessToken[];
     readonly memo?: string;
     readonly receivedAt: number;
 }
@@ -150,6 +177,11 @@ interface SendRequest {
     coinId: string;
     memo?: string;
 }
+interface SendCoinlessRequest {
+    recipient: string;
+    tokenId: string;
+    memo?: string;
+}
 interface MintResult {
     success: boolean;
     tokenId?: string;
@@ -219,6 +251,8 @@ interface PendingTransfer {
     recipient: string;
     coinId: string;
     amount: string;
+    /** Set instead of coinId/amount when the intent is a token-addressed spend. */
+    tokenId?: string;
     legs: {
         certified: number;
         total: number;
@@ -234,11 +268,14 @@ interface PaymentsV2 {
     tokens(filter?: {
         coinId?: string;
     }): Token[];
+    coinless(): CoinlessToken[];
+    tokenData(tokenId: string): Promise<Uint8Array | null>;
     history(page?: {
         before?: string;
         limit?: number;
     }): Promise<HistoryPage>;
     send(req: SendRequest): Promise<TransferResult>;
+    sendCoinless(req: SendCoinlessRequest): Promise<TransferResult>;
     mint(coinId: string, amount: bigint): Promise<MintResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
@@ -278,7 +315,9 @@ interface InventoryItem {
     status: 'active' | 'removed';
     seq: number;
     stateHash: string;
+    /** Absent for a tombstone AND for an active COINLESS token — read `status`, not this. */
     assets?: InventoryAsset[];
+    tokenType?: string;
 }
 interface InventoryPage {
     cursor: number;
@@ -362,23 +401,33 @@ interface RetryableAckError extends Error {
 }
 declare function isRetryableAckError(err: unknown): err is RetryableAckError;
 
-interface IntentPayload {
+interface IntentPayloadBase {
     v: 2;
     recipient: string;
-    coinId: string;
-    amount: string;
     memo?: string;
     direct: string[];
+    spentStates?: Record<string, {
+        local: string;
+        protocol: string;
+    }>;
+}
+interface CoinIntentPayload extends IntentPayloadBase {
+    kind: 'coin';
+    coinId: string;
+    amount: string;
     split?: {
         tokenId: string;
         splitAmount: string;
         remainderAmount: string;
     };
-    spentStates?: Record<string, {
-        local: string;
-        protocol: string;
-    }>;
 }
+interface CoinlessIntentPayload extends IntentPayloadBase {
+    kind: 'coinless';
+    direct: [string];
+    split?: undefined;
+}
+/** `kind` is REQUIRED on both arms: a missed writer must be a compile error. */
+type IntentPayload = CoinIntentPayload | CoinlessIntentPayload;
 interface PlannedOp {
     kind: 'direct' | 'split';
     opIndex: number;
@@ -558,6 +607,9 @@ declare const STORE_KEYS: {
     readonly knownSpends: "known-spends";
 };
 
+/** `none_*` = coinless; `bare_collection` = a dialect this SDK cannot read. */
+type ValueEnvelope = 'sphere' | 'bare_collection' | 'none_tag' | 'none_other' | 'none_absent';
+
 /**
  * token-engine/types.ts — the FROZEN, sphere-domain contract surface.
  *
@@ -618,6 +670,22 @@ interface SphereToken {
     readonly blob: TokenBlob;
     /** Decoded value (cached); null when the token carries no sphere payment data. */
     readonly value: SphereValue | null;
+    /**
+     * Which value envelope the genesis payload carried (#778). Distinguishes the
+     * reasons `value` is null, which the old boolean predicate collapsed:
+     * `'none_*'` means the token genuinely names no coin — a COINLESS token — while
+     * `'bare_collection'` means it carries coins in the bridged dialect this SDK
+     * does not decode, so a zero here is "cannot read", not "has none". A corrupt
+     * envelope never reaches this field: it throws during classification.
+     */
+    readonly valueEnvelope: ValueEnvelope;
+    /**
+     * Genesis `TokenType`, lowercase hex. The token's CLASS, never its instance —
+     * `blob.tokenId` is the instance key (wallet-api#147). Only as meaningful as its
+     * minter made it: `mint()` and split outputs derive one per operation, so for
+     * value tokens it is per-mint noise. Never a spend gate.
+     */
+    readonly tokenType: string;
 }
 interface MintParams {
     /** Recipient's 33-byte compressed chain pubkey; engine derives the predicate. */
@@ -1003,6 +1071,11 @@ interface RegistryReader {
     getName(coinId: string): string;
     getDecimals(coinId: string): number;
     getIconUrl(coinId: string): string | null;
+    /** Coinless token CLASS metadata, keyed by token type — a separate namespace. */
+    getTypeMeta?(tokenType: string): {
+        name: string;
+        iconUrl: string | null;
+    } | null;
 }
 interface PriceQuote {
     readonly priceUsd: number;
@@ -1152,6 +1225,8 @@ declare class PaymentsFacade implements PaymentsV2 {
     tokens(filter?: {
         coinId?: string;
     }): Token[];
+    coinless(): CoinlessToken[];
+    tokenData(tokenId: string): Promise<Uint8Array | null>;
     history(page?: {
         before?: string;
         limit?: number;
@@ -1164,6 +1239,7 @@ declare class PaymentsFacade implements PaymentsV2 {
     discardPrewarm(): void;
     private warmDeps;
     send(request: SendRequest): Promise<TransferResult>;
+    sendCoinless(request: SendCoinlessRequest): Promise<TransferResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
     }>;
@@ -1175,9 +1251,13 @@ declare class PaymentsFacade implements PaymentsV2 {
     private runConvergencePass;
     private convergeBody;
     private nowMs;
+    private mintDeps;
     /** The ONE place a send() outcome is shaped: success emits in finishSend, a
      *  CLEAN rejection emits `transfer:updated{status:'failed'}` here (§4). */
     private sendOutcome;
+    /** A token spend has no amount; '0' keeps the shortfall arithmetic total-free. */
+    private sendCoinlessOutcome;
+    private runJob;
     /** Only a CLEAN failure (nothing certified, classifyError 'other') is 'failed'.
      *  Keep-open/partial/conflict outcomes are pending/converging — labelling them
      *  'failed' invites a dApp re-send, i.e. a double-pay (#631/#676). */
@@ -1209,13 +1289,8 @@ declare class PaymentsFacade implements PaymentsV2 {
     private accumulate;
     private finishSend;
     /** Nothing delivered → UNWRAPPED; after ≥1 delivered leg every failure surfaces as PartialSendConflictError over the settled set. */
-    private partialize;
-    /** #441: possibly-committed errors must carry the transferId for the settling journal. */
-    private stampTransferId;
     private softAbort;
     private mintInner;
-    private mintUnderJournal;
-    private finalizeMint;
     /** @returns how many journal entries were RESOLVED (cleared) — heartbeat progress. */
     private replayMints;
     private replayMint;
@@ -1230,4 +1305,4 @@ declare class PaymentsFacade implements PaymentsV2 {
 declare const HEARTBEAT_SEED_MS = 5000;
 declare const HEARTBEAT_CAP_MS = 120000;
 
-export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, isRetryableAckError, supportsDeterministicMint, sweepSupersededState };
+export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendCoinlessRequest, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, isRetryableAckError, supportsDeterministicMint, sweepSupersededState };

package/dist/modules/payments-v2/index.d.ts

@@ -56,6 +56,31 @@ interface Token {
      */
     suspectedSpent?: boolean;
 }
+/**
+ * A holding that names no coin (wallet-api#140) — an NFT. Deliberately NOT a
+ * `Token`: no amount, decimals or symbol, and never returned by `tokens()` or
+ * counted in `assets()`. `tokenType` names the token's CLASS and `tokenId` the
+ * instance (wallet-api#147). The payload is read with `payments.tokenData()`.
+ */
+interface CoinlessToken {
+    readonly tokenId: string;
+    readonly tokenType?: string;
+    /**
+     * Class metadata resolved from the registry THIS wallet owns, when the type is
+     * recognised. Resolved here so callers never reach for a registry themselves:
+     * the process-global singleton is repointable by another Sphere's init, so a
+     * second wallet on another network would retarget it (#767).
+     */
+    readonly name?: string;
+    readonly iconUrl?: string;
+    readonly stateHash: string;
+    /** #737: reserved by a converging transfer — not spendable right now. */
+    readonly transferring: boolean;
+    /** #625: proven spent on-chain; excluded from spend selection. */
+    readonly suspectedSpent?: boolean;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
 interface Asset {
     readonly coinId: string;
     readonly symbol: string;
@@ -126,6 +151,8 @@ interface IncomingTransfer {
     readonly senderPubkey: string;
     readonly senderNametag?: string;
     readonly tokens: Token[];
+    /** Arrivals that name no coin (#777). Disjoint from `tokens`, never a zero Token. */
+    readonly coinless?: CoinlessToken[];
     readonly memo?: string;
     readonly receivedAt: number;
 }
@@ -150,6 +177,11 @@ interface SendRequest {
     coinId: string;
     memo?: string;
 }
+interface SendCoinlessRequest {
+    recipient: string;
+    tokenId: string;
+    memo?: string;
+}
 interface MintResult {
     success: boolean;
     tokenId?: string;
@@ -219,6 +251,8 @@ interface PendingTransfer {
     recipient: string;
     coinId: string;
     amount: string;
+    /** Set instead of coinId/amount when the intent is a token-addressed spend. */
+    tokenId?: string;
     legs: {
         certified: number;
         total: number;
@@ -234,11 +268,14 @@ interface PaymentsV2 {
     tokens(filter?: {
         coinId?: string;
     }): Token[];
+    coinless(): CoinlessToken[];
+    tokenData(tokenId: string): Promise<Uint8Array | null>;
     history(page?: {
         before?: string;
         limit?: number;
     }): Promise<HistoryPage>;
     send(req: SendRequest): Promise<TransferResult>;
+    sendCoinless(req: SendCoinlessRequest): Promise<TransferResult>;
     mint(coinId: string, amount: bigint): Promise<MintResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
@@ -278,7 +315,9 @@ interface InventoryItem {
     status: 'active' | 'removed';
     seq: number;
     stateHash: string;
+    /** Absent for a tombstone AND for an active COINLESS token — read `status`, not this. */
     assets?: InventoryAsset[];
+    tokenType?: string;
 }
 interface InventoryPage {
     cursor: number;
@@ -362,23 +401,33 @@ interface RetryableAckError extends Error {
 }
 declare function isRetryableAckError(err: unknown): err is RetryableAckError;
 
-interface IntentPayload {
+interface IntentPayloadBase {
     v: 2;
     recipient: string;
-    coinId: string;
-    amount: string;
     memo?: string;
     direct: string[];
+    spentStates?: Record<string, {
+        local: string;
+        protocol: string;
+    }>;
+}
+interface CoinIntentPayload extends IntentPayloadBase {
+    kind: 'coin';
+    coinId: string;
+    amount: string;
     split?: {
         tokenId: string;
         splitAmount: string;
         remainderAmount: string;
     };
-    spentStates?: Record<string, {
-        local: string;
-        protocol: string;
-    }>;
 }
+interface CoinlessIntentPayload extends IntentPayloadBase {
+    kind: 'coinless';
+    direct: [string];
+    split?: undefined;
+}
+/** `kind` is REQUIRED on both arms: a missed writer must be a compile error. */
+type IntentPayload = CoinIntentPayload | CoinlessIntentPayload;
 interface PlannedOp {
     kind: 'direct' | 'split';
     opIndex: number;
@@ -558,6 +607,9 @@ declare const STORE_KEYS: {
     readonly knownSpends: "known-spends";
 };
 
+/** `none_*` = coinless; `bare_collection` = a dialect this SDK cannot read. */
+type ValueEnvelope = 'sphere' | 'bare_collection' | 'none_tag' | 'none_other' | 'none_absent';
+
 /**
  * token-engine/types.ts — the FROZEN, sphere-domain contract surface.
  *
@@ -618,6 +670,22 @@ interface SphereToken {
     readonly blob: TokenBlob;
     /** Decoded value (cached); null when the token carries no sphere payment data. */
     readonly value: SphereValue | null;
+    /**
+     * Which value envelope the genesis payload carried (#778). Distinguishes the
+     * reasons `value` is null, which the old boolean predicate collapsed:
+     * `'none_*'` means the token genuinely names no coin — a COINLESS token — while
+     * `'bare_collection'` means it carries coins in the bridged dialect this SDK
+     * does not decode, so a zero here is "cannot read", not "has none". A corrupt
+     * envelope never reaches this field: it throws during classification.
+     */
+    readonly valueEnvelope: ValueEnvelope;
+    /**
+     * Genesis `TokenType`, lowercase hex. The token's CLASS, never its instance —
+     * `blob.tokenId` is the instance key (wallet-api#147). Only as meaningful as its
+     * minter made it: `mint()` and split outputs derive one per operation, so for
+     * value tokens it is per-mint noise. Never a spend gate.
+     */
+    readonly tokenType: string;
 }
 interface MintParams {
     /** Recipient's 33-byte compressed chain pubkey; engine derives the predicate. */
@@ -1003,6 +1071,11 @@ interface RegistryReader {
     getName(coinId: string): string;
     getDecimals(coinId: string): number;
     getIconUrl(coinId: string): string | null;
+    /** Coinless token CLASS metadata, keyed by token type — a separate namespace. */
+    getTypeMeta?(tokenType: string): {
+        name: string;
+        iconUrl: string | null;
+    } | null;
 }
 interface PriceQuote {
     readonly priceUsd: number;
@@ -1152,6 +1225,8 @@ declare class PaymentsFacade implements PaymentsV2 {
     tokens(filter?: {
         coinId?: string;
     }): Token[];
+    coinless(): CoinlessToken[];
+    tokenData(tokenId: string): Promise<Uint8Array | null>;
     history(page?: {
         before?: string;
         limit?: number;
@@ -1164,6 +1239,7 @@ declare class PaymentsFacade implements PaymentsV2 {
     discardPrewarm(): void;
     private warmDeps;
     send(request: SendRequest): Promise<TransferResult>;
+    sendCoinless(request: SendCoinlessRequest): Promise<TransferResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
     }>;
@@ -1175,9 +1251,13 @@ declare class PaymentsFacade implements PaymentsV2 {
     private runConvergencePass;
     private convergeBody;
     private nowMs;
+    private mintDeps;
     /** The ONE place a send() outcome is shaped: success emits in finishSend, a
      *  CLEAN rejection emits `transfer:updated{status:'failed'}` here (§4). */
     private sendOutcome;
+    /** A token spend has no amount; '0' keeps the shortfall arithmetic total-free. */
+    private sendCoinlessOutcome;
+    private runJob;
     /** Only a CLEAN failure (nothing certified, classifyError 'other') is 'failed'.
      *  Keep-open/partial/conflict outcomes are pending/converging — labelling them
      *  'failed' invites a dApp re-send, i.e. a double-pay (#631/#676). */
@@ -1209,13 +1289,8 @@ declare class PaymentsFacade implements PaymentsV2 {
     private accumulate;
     private finishSend;
     /** Nothing delivered → UNWRAPPED; after ≥1 delivered leg every failure surfaces as PartialSendConflictError over the settled set. */
-    private partialize;
-    /** #441: possibly-committed errors must carry the transferId for the settling journal. */
-    private stampTransferId;
     private softAbort;
     private mintInner;
-    private mintUnderJournal;
-    private finalizeMint;
     /** @returns how many journal entries were RESOLVED (cleared) — heartbeat progress. */
     private replayMints;
     private replayMint;
@@ -1230,4 +1305,4 @@ declare class PaymentsFacade implements PaymentsV2 {
 declare const HEARTBEAT_SEED_MS = 5000;
 declare const HEARTBEAT_CAP_MS = 120000;
 
-export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, isRetryableAckError, supportsDeterministicMint, sweepSupersededState };
+export { ATTENTION_MINT_UNRESOLVED, ATTENTION_RECIPIENT_NETWORK_UNVERIFIED, ATTENTION_RESEED_REJECTED, type AckOutcome, type AckRequest, type ApplyDeltaResult, type CheckpointReseeder, type ConnectionStatus, type DeliverOptions, type DeliveryJournalEntry, type DeliveryPort, type DeliveryReceipt, type DeterministicMintCapable, type FacadeClient, type FacadeSession, HEARTBEAT_CAP_MS, HEARTBEAT_SEED_MS, type HistoryEntry, type HistoryPage, type IncomingDelivery, type IntentBackstopEntry, type IntentPayload, type InventoryAsset, type InventoryItem, type InventoryPage, MAX_RESELECT, type MintJournalEntry, type MintResult, type OpOutcome, type OutcomeClass, type PaymentRequestStatus, type PaymentRequestView, PaymentsFacade, type PaymentsFacadeDeps, type PaymentsRequestsApi, type PaymentsV2, type PaymentsV2Events, type PendingTransfer, type PlannedOp, type RecipientInfo, type RetryableAckError, STORE_KEYS, type ScopedKV, type SendCoinlessRequest, type SendRequest, type SettlingLink, type ShortfallEntry, type StoragePort, type StreamCursor, type StreamName, createScopedKV, isRetryableAckError, supportsDeterministicMint, sweepSupersededState };