@unicitylabs/sphere-sdk 0.16.0 → 0.17.1

package/dist/core/index.d.cts

@@ -89,6 +89,11 @@ interface SendRequest {
     coinId: string;
     memo?: string;
 }
+interface SendWholeTokenRequest {
+    recipient: string;
+    tokenId: string;
+    memo?: string;
+}
 interface MintResult {
     success: boolean;
     tokenId?: string;
@@ -158,6 +163,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;
@@ -173,11 +180,16 @@ 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>;
+    sendWholeToken(req: SendWholeTokenRequest): Promise<TransferResult>;
+    /** NFT-scoped twin: refuses a valued source. Connect's `send_nft` routes here. */
+    sendCoinless(req: SendWholeTokenRequest): Promise<TransferResult>;
     mint(coinId: string, amount: bigint): Promise<MintResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
@@ -526,6 +538,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;
@@ -596,6 +633,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;
 }
@@ -2292,6 +2331,9 @@ interface DerivedAddressInfo {
  */
 declare function discoverAddressesImpl(deriveTransportPubkey: (index: number) => DerivedAddressInfo, batchResolve: (transportPubkeys: string[]) => Promise<PeerInfo[]>, options?: DiscoverAddressesOptions): Promise<DiscoverAddressesResult>;
 
+/** `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.
  *
@@ -2352,6 +2394,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. */
@@ -2767,7 +2825,18 @@ interface InventoryItemWire {
     status: 'active' | 'removed';
     seq: number;
     stateHash: string;
+    /**
+     * Omitted for a tombstone AND for an ACTIVE COINLESS token (wallet-api#140),
+     * so absence is never "removed" or "not loaded" — discriminate on `status`.
+     */
     assets?: AssetWire[];
+    /**
+     * Genesis `TokenType`, lowercase hex (1-64 bytes ⇒ 2-128 chars). Names the
+     * token's CLASS, not the instance (wallet-api#147). Absent on rows written
+     * before wallet-api migration 0015. An unrecognised type is legitimate: never
+     * reject or hide a token for it.
+     */
+    tokenType?: string;
 }
 interface InventoryPageWire {
     cursor: number;

package/dist/core/index.d.ts

@@ -89,6 +89,11 @@ interface SendRequest {
     coinId: string;
     memo?: string;
 }
+interface SendWholeTokenRequest {
+    recipient: string;
+    tokenId: string;
+    memo?: string;
+}
 interface MintResult {
     success: boolean;
     tokenId?: string;
@@ -158,6 +163,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;
@@ -173,11 +180,16 @@ 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>;
+    sendWholeToken(req: SendWholeTokenRequest): Promise<TransferResult>;
+    /** NFT-scoped twin: refuses a valued source. Connect's `send_nft` routes here. */
+    sendCoinless(req: SendWholeTokenRequest): Promise<TransferResult>;
     mint(coinId: string, amount: bigint): Promise<MintResult>;
     receive(): Promise<{
         transfers: IncomingTransfer[];
@@ -526,6 +538,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;
@@ -596,6 +633,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;
 }
@@ -2292,6 +2331,9 @@ interface DerivedAddressInfo {
  */
 declare function discoverAddressesImpl(deriveTransportPubkey: (index: number) => DerivedAddressInfo, batchResolve: (transportPubkeys: string[]) => Promise<PeerInfo[]>, options?: DiscoverAddressesOptions): Promise<DiscoverAddressesResult>;
 
+/** `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.
  *
@@ -2352,6 +2394,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. */
@@ -2767,7 +2825,18 @@ interface InventoryItemWire {
     status: 'active' | 'removed';
     seq: number;
     stateHash: string;
+    /**
+     * Omitted for a tombstone AND for an ACTIVE COINLESS token (wallet-api#140),
+     * so absence is never "removed" or "not loaded" — discriminate on `status`.
+     */
     assets?: AssetWire[];
+    /**
+     * Genesis `TokenType`, lowercase hex (1-64 bytes ⇒ 2-128 chars). Names the
+     * token's CLASS, not the instance (wallet-api#147). Absent on rows written
+     * before wallet-api migration 0015. An unrecognised type is legitimate: never
+     * reject or hide a token for it.
+     */
+    tokenType?: string;
 }
 interface InventoryPageWire {
     cursor: number;