@unicitylabs/sphere-sdk 0.9.0-dev.0 → 0.9.0-dev.1

package/dist/token-engine/index.d.ts

@@ -0,0 +1,363 @@
+import { Token } from '@unicitylabs/state-transition-sdk/lib/transaction/Token.js';
+import { IPaymentData } from '@unicitylabs/state-transition-sdk/lib/payment/IPaymentData.js';
+import { Asset } from '@unicitylabs/state-transition-sdk/lib/payment/asset/Asset.js';
+import { PaymentAssetCollection } from '@unicitylabs/state-transition-sdk/lib/payment/asset/PaymentAssetCollection.js';
+
+/**
+ * token-engine/types.ts — the FROZEN, sphere-domain contract surface.
+ *
+ * Design rule (anti-corruption): the public ITokenEngine port speaks ONLY
+ * sphere-domain types — `Uint8Array` pubkeys, `string` coin ids, `bigint`
+ * amounts, plain enums. The v2 state-transition SDK has exactly ONE foothold
+ * here: `SphereToken.sdkToken`, an OPAQUE handle. Callers must treat it as
+ * opaque (store it, hand it back to the engine) and never call methods on it —
+ * they cannot, since the ESLint boundary forbids them importing the SDK.
+ *
+ * Both migration tracks freeze against this file:
+ *   Track A implements it (token-engine internals).
+ *   Track B codes callers against it (using FakeTokenEngine until A lands).
+ */
+
+/** The wallet identity at the engine boundary. The private key never appears in a DTO. */
+interface EngineIdentity {
+    /** 33-byte compressed secp256k1 public key (stable across the migration — Path A). */
+    readonly chainPubkey: Uint8Array;
+}
+/** Which Unicity network a token/engine lives on. Maps to the SDK NetworkId inside the engine. */
+type SphereNetwork = 'mainnet' | 'testnet' | 'local';
+/**
+ * Coin identifier. Canonical form is the lowercase hex of the v2 AssetId;
+ * human symbols (e.g. "ALPHA") are resolved to hex via the registry before use.
+ */
+type CoinId = string;
+/** One fungible position inside a token. */
+interface SphereAsset {
+    readonly coinId: CoinId;
+    readonly amount: bigint;
+}
+/** The decoded, app-defined value carried by a token (v2 Token itself is value-less). */
+interface SphereValue {
+    readonly assets: readonly SphereAsset[];
+}
+/**
+ * Storage-and-display token. Format version + network let storage migrate
+ * independently of the SDK's own CBOR. The decoded value is re-derivable from
+ * `token`, so it is NOT stored — only cached at runtime on SphereToken.value.
+ */
+interface TokenBlob {
+    /** Blob format version (sphere storage migrations; independent of SDK CBOR). */
+    readonly v: number;
+    /** NetworkId.id the token belongs to (mainnet=1 / testnet=2 / local=3). */
+    readonly network: number;
+    /**
+     * Genesis-stable token id — 64-char lowercase hex of the v2 `TokenId.bytes`
+     * (same across every state of the token). Stored on the blob so dedup / listing
+     * / tombstone keys need no engine call. `createTokenStateKey = ${tokenId}_${hash}`.
+     */
+    readonly tokenId: string;
+    /** CBOR bytes of the v2 Token (`Token.toCBOR()`). */
+    readonly token: Uint8Array;
+}
+/**
+ * A wallet token. `sdkToken` is the OPAQUE engine handle (see file header) —
+ * present for the engine to operate on, never to be touched by callers.
+ */
+interface SphereToken {
+    /** Opaque v2 SDK handle. Do not call methods on this outside token-engine/. */
+    readonly sdkToken: Token;
+    /** Serializable form for storage/transport. */
+    readonly blob: TokenBlob;
+    /** Decoded value (cached); null when the token carries no sphere payment data. */
+    readonly value: SphereValue | null;
+}
+interface MintParams {
+    /** Recipient's 33-byte compressed chain pubkey; engine derives the predicate. */
+    readonly recipientPubkey: Uint8Array;
+    /** Value to embed in the mint; null mints a value-less token. */
+    readonly value?: SphereValue | null;
+}
+/**
+ * Mint a NON-value (data) token: arbitrary opaque `data` (e.g. serialized invoice
+ * terms), a custom `tokenType`, and a deterministic `salt` → a stable,
+ * terms-derived `tokenId`. The minted token has `value === null` (it carries data,
+ * not coins); read the bytes back with `readTokenData`.
+ */
+interface MintDataTokenParams {
+    readonly recipientPubkey: Uint8Array;
+    /** Opaque token payload (the engine does not interpret it). */
+    readonly data: Uint8Array;
+    /** Token type bytes; defaults to a random type when omitted. */
+    readonly tokenType?: Uint8Array;
+    /** Salt bytes; deterministic salt → deterministic (terms-derived) tokenId. */
+    readonly salt?: Uint8Array;
+}
+interface TransferParams {
+    /** The token to spend (must be owned by this engine's identity). */
+    readonly token: SphereToken;
+    /** Recipient's 33-byte compressed chain pubkey. */
+    readonly recipientPubkey: Uint8Array;
+    /** Optional opaque on-chain memo carried on the transfer (read back via `readMemo`). */
+    readonly data?: Uint8Array;
+}
+/**
+ * One split output = one single-coin token. To split a multi-coin token, emit
+ * one output per coin (the recipient receives the value as several tokens; the
+ * SDK enforces per-coin conservation). If a single multi-coin output token is
+ * ever needed, generalize this to `assets: readonly SphereAsset[]` (additive).
+ */
+interface SplitOutput {
+    readonly recipientPubkey: Uint8Array;
+    readonly coinId: CoinId;
+    readonly amount: bigint;
+    /** Optional opaque memo carried in this output's value envelope (read back via `readMemo`). */
+    readonly data?: Uint8Array;
+}
+interface SplitParams {
+    /** The token to split (its total per coin must equal the sum of outputs). */
+    readonly token: SphereToken;
+    /** Desired outputs; value conservation is enforced by the SDK split. */
+    readonly outputs: readonly SplitOutput[];
+}
+interface SplitResult {
+    /**
+     * One minted token per requested output, **index-aligned with
+     * `SplitParams.outputs`** — `outputs[i]` is the token for `params.outputs[i]`
+     * (so a payee/change split can rely on positional order). Guaranteed by both
+     * the real engine and FakeTokenEngine.
+     */
+    readonly outputs: readonly SphereToken[];
+}
+/** Verification outcome, flattened to sphere-domain (no SDK status enum leaks). */
+interface EngineVerifyResult {
+    readonly ok: boolean;
+    /** Human-readable reason when `ok` is false (mapped from the SDK verification status). */
+    readonly reason?: string;
+}
+
+/**
+ * token-engine/engine.ts — the FROZEN public port (ITokenEngine) + its config.
+ *
+ * This is the contract both migration tracks build against. It is sphere-domain
+ * only (see types.ts). The granular, SDK-typed steps (buildMint, submit,
+ * awaitProof, certify, …) are an INTERNAL concern of the real adapter and are
+ * intentionally NOT part of this public interface.
+ */
+
+/** Options common to the long-running, network-bound operations. */
+interface EngineOpOptions {
+    /** Cancels the operation (including inclusion-proof polling). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * The token engine port. The wallet's secp256k1 identity, the target network,
+ * the aggregator client and the trust base are all bound at construction
+ * (see EngineConfig); operations below take only sphere-domain arguments.
+ */
+interface ITokenEngine {
+    /** This engine's wallet identity (chain pubkey). Synchronous. */
+    getIdentity(): EngineIdentity;
+    /**
+     * Legacy `DIRECT://` address for the given pubkey (defaults to this engine's
+     * identity). This is the ONLY "address" in v2 and is kept stable across the
+     * migration (Path A) so Quest XP / Unicity IDs keyed on it survive. Async —
+     * the derivation hashes via the SDK.
+     */
+    deriveIdentityAddress(pubkey?: Uint8Array): Promise<string>;
+    /**
+     * Genesis-stable token id — 64-char lowercase hex of the v2 TokenId (same
+     * across every state). Use for dedup / history / tombstone keys. Synchronous.
+     */
+    tokenId(token: SphereToken): string;
+    /** Decoded value of a token (cached). Synchronous. */
+    readValue(token: SphereToken): SphereValue | null;
+    /** Balance of a single coin within a token. Synchronous. */
+    balanceOf(token: SphereToken, coinId: CoinId): bigint;
+    /**
+     * The opaque on-chain memo delivered with this token: the latest transfer's
+     * data for a transferred token, else the memo in a minted output's value
+     * envelope (split). Returns `null` when there is no memo — including for data
+     * tokens (no value envelope; use `readTokenData`) and memo-less value tokens.
+     * To tell a data token from a value token, check `readValue` (null ⇒
+     * data/value-less token). Synchronous.
+     */
+    readMemo(token: SphereToken): Uint8Array | null;
+    /** Raw genesis data of a token (e.g. a data-token's terms). `null` when absent. Synchronous. */
+    readTokenData(token: SphereToken): Uint8Array | null;
+    /**
+     * Mint (issue) a new token to a recipient pubkey. NOT a wallet end-user flow —
+     * this is the issuer/developer capability: an app issuing its own tokens
+     * (rewards, in-app currency, tickets) to users, or seeding test balances. v2
+     * makes standalone mint first-class (Token.mint accepts a genesis with a null
+     * justification). Split's per-output mint is a separate, internal path; the
+     * Unicity-ID/nametag mint is a distinct identity surface (see migration plan §4.4).
+     */
+    mint(params: MintParams, options?: EngineOpOptions): Promise<SphereToken>;
+    /**
+     * Mint a NON-value (data) token: opaque `data` + custom `tokenType` + deterministic
+     * `salt` → a stable, terms-derived `tokenId`. The result has `value === null`;
+     * read its bytes via `readTokenData`. (Used e.g. for on-chain invoice tokens.)
+     */
+    mintDataToken(params: MintDataTokenParams, options?: EngineOpOptions): Promise<SphereToken>;
+    /** Spend a token wholesale to a recipient pubkey; returns the recipient's finished token. */
+    transfer(params: TransferParams, options?: EngineOpOptions): Promise<SphereToken>;
+    /** Split a token into N value-conserving outputs (burn source + internally mint each output). */
+    split(params: SplitParams, options?: EngineOpOptions): Promise<SplitResult>;
+    /** Fully verify a token against the trust base. */
+    verify(token: SphereToken, options?: EngineOpOptions): Promise<EngineVerifyResult>;
+    /** Whether the token's current state has already been spent on the network. */
+    isSpent(token: SphereToken, options?: EngineOpOptions): Promise<boolean>;
+    /**
+     * Whether the token's CURRENT state is locked to `SignaturePredicate(pubkey)`.
+     * Local + synchronous (predicate byte-compare, no network). The receive path
+     * uses it to reject tokens that are not actually addressed to this wallet.
+     */
+    isOwnedBy(token: SphereToken, pubkey: Uint8Array): boolean;
+    /** Serialize a token for storage/transport. Synchronous. */
+    encodeToken(token: SphereToken): TokenBlob;
+    /** Reconstruct a token from its blob (decodes embedded payment data). */
+    decodeToken(blob: TokenBlob): Promise<SphereToken>;
+}
+/**
+ * Engine construction config. Sphere-domain inputs only: the factory maps
+ * `network` → SDK NetworkId, builds the aggregator client from `aggregatorUrl`,
+ * the signing service from `privateKey`, and loads the trust base internally.
+ *
+ * NOTE: trust-base sourcing + proof-policy defaults are finalized in Phase 0.8;
+ * this shape may gain fields there without affecting the ITokenEngine contract.
+ */
+interface EngineConfig {
+    /** Aggregator (gateway) base URL the StateTransitionClient talks to. */
+    readonly aggregatorUrl: string;
+    /** Optional gateway API key (some gateways, e.g. testnet2, require it for auth). */
+    readonly apiKey?: string;
+    /** Wallet signing key (secp256k1 private scalar, 32 bytes). Held inside the engine only. */
+    readonly privateKey: Uint8Array;
+    /**
+     * Root-trust-base JSON. The single source of truth for the network — the engine's
+     * NetworkId is taken from it (`RootTrustBase.networkId` via `NetworkId.fromId`), so
+     * any network id works (e.g. testnet2 = 4) with no enum entry. Typed `unknown` to
+     * keep SDK types off the public surface (the factory parses it internally).
+     */
+    readonly trustBaseJson: unknown;
+    /** Inclusion-proof poll cadence in ms (engine owns the await policy; Spike S1). */
+    readonly proofPollIntervalMs?: number;
+    /** Inclusion-proof overall timeout in ms (0/undefined = no engine-side cap). */
+    readonly proofTimeoutMs?: number;
+}
+/** Factory signature for the real adapter (implemented in Track A). */
+type CreateTokenEngine = (config: EngineConfig) => Promise<ITokenEngine>;
+
+/**
+ * Derive the legacy `DIRECT://` identity address for a compressed (33-byte)
+ * secp256k1 public key. Deterministic; byte-identical to the v1 path (Path A).
+ */
+declare function deriveDirectAddress(publicKey: Uint8Array): Promise<string>;
+
+/**
+ * token-engine/factory.ts — the real engine constructor (A4).
+ *
+ * `createSphereTokenEngine` is the public way to obtain an ITokenEngine. It maps
+ * the sphere-domain EngineConfig to the SDK objects the engine needs: the
+ * aggregator client (from `aggregatorUrl`), the trust base (parsed from
+ * `trustBaseJson`), the wallet signing key (from `privateKey`), the network id,
+ * and a mint-justification verifier with the split verifier registered (so
+ * split-output tokens verify).
+ *
+ * Loading the trust base per environment (browser fetch / node file) stays with
+ * the caller (impl/<env>/oracle, reusing the existing trust-base loaders); it
+ * passes the parsed JSON in via `trustBaseJson`, keeping this factory env-agnostic.
+ */
+
+declare function createSphereTokenEngine(config: EngineConfig): Promise<ITokenEngine>;
+
+/**
+ * token-engine/unicity-id.ts — self-issued v2 UnicityIdToken mint (the v2 analog
+ * of the v1 nametag-token mint).
+ *
+ * User decision 2026-06-10: the on-chain Unicity ID claim is minted AND STORED
+ * again at nametag registration (it was retired with v1 in Track B / D5), but it
+ * is NOT used at runtime — name resolution stays Nostr-binding-only, receive
+ * stays SignaturePredicate(chainPubkey), and no PROXY semantics return. The
+ * token is kept for the future (e.g. an issuer/verification model).
+ *
+ * Trust model: SELF-ISSUED. The wallet's own key is the issuer lock script, the
+ * recipient AND the target predicate (the v2 local-mint path — the issuer pin is
+ * only meaningful when verifying third-party tokens). Because the issuer lock
+ * script is part of the StateId, on-chain uniqueness is per-issuer only; GLOBAL
+ * name uniqueness remains the Nostr first-seen-wins binding's job (unchanged).
+ *
+ * Determinism / idempotency: tokenId = SHA256(CBOR["NAMETAG_", null, name]),
+ * tokenType is pinned (UNICITY_TOKEN_TYPE_HEX), and all predicates derive from
+ * the wallet key — the whole mint transaction is reproducible byte-for-byte, so
+ * a re-mint (e.g. after the token was lost from local storage) re-certifies the
+ * same state and yields the identical token (the v1 REQUEST_ID_EXISTS recovery
+ * analog).
+ */
+
+interface UnicityIdMintResult {
+    /** UnicityIdToken CBOR, hex-encoded — the storable form (UnicityIdToken.fromCBOR round-trips it). */
+    readonly tokenCborHex: string;
+    /** 64-char hex token id, derived from the name (stable across re-mints). */
+    readonly tokenId: string;
+}
+/** Self-issued Unicity ID (nametag) token minter. */
+interface IUnicityIdMinter {
+    /**
+     * Mint (or idempotently re-certify) the UnicityIdToken for `name`,
+     * self-issued by this wallet's key. Network-bound: submits the certification
+     * request and waits for the inclusion proof.
+     */
+    mintUnicityIdToken(name: string, options?: EngineOpOptions): Promise<UnicityIdMintResult>;
+}
+/**
+ * Build the self-issued Unicity ID minter from the same config the token engine
+ * uses (trust base JSON + gateway URL + API key + wallet key).
+ */
+declare function createUnicityIdMinter(config: EngineConfig): IUnicityIdMinter;
+
+/**
+ * token-engine/SpherePaymentData.ts — the sphere value model.
+ *
+ * v2 `Token` carries no coins; value is app-defined and stored in
+ * `MintTransaction.data`. `SpherePaymentData` is that payload: it implements the
+ * SDK's `IPaymentData` (so `TokenSplit` can read it for value conservation) and
+ * encodes a `PaymentAssetCollection` inside a versioned, tagged CBOR envelope.
+ *
+ * The SDK never inspects our raw bytes — it only calls `decodePaymentData(data)`
+ * and reads `.assets` — so the envelope (tag + version) is ours, chosen for
+ * forward-compatible storage. `fromValue`/`toValue` bridge sphere-domain values
+ * (hex coin id + bigint amount) to/from the SDK asset collection.
+ */
+
+/** Validate a sphere-domain asset and build the SDK Asset — the single validation point. */
+declare function sphereAssetToSdk(coinId: CoinId, amount: bigint): Asset;
+declare class SpherePaymentData implements IPaymentData {
+    readonly assets: PaymentAssetCollection;
+    private readonly _memo;
+    /** Sphere-private CBOR tag (verified free in the v2 SDK tag space). */
+    static readonly CBOR_TAG = 39050n;
+    /** Envelope version; bump when the structure changes. */
+    static readonly VERSION = 1n;
+    private constructor();
+    /** Opaque, app-defined memo carried alongside the value (e.g. invoice attribution). */
+    get memo(): Uint8Array | null;
+    /** Wrap an existing SDK asset collection (+ optional opaque memo). */
+    static create(assets: PaymentAssetCollection, memo?: Uint8Array | null): SpherePaymentData;
+    /** Build from a sphere-domain value (hex coin id → bigint amount) + optional opaque memo. */
+    static fromValue(value: SphereValue, memo?: Uint8Array | null): SpherePaymentData;
+    /** Decode from the CBOR envelope produced by {@link encode}. */
+    static fromCBOR(bytes: Uint8Array): SpherePaymentData;
+    /** Deterministic, versioned, tagged CBOR: `tag(39050)[ version, assets, memo? ]`. */
+    encode(): Promise<Uint8Array>;
+    /** Project to a sphere-domain value (hex coin id + bigint amount), preserving order. */
+    toValue(): SphereValue;
+    /** Balance of a single coin within this payload (0n when absent). */
+    balanceOf(coinId: CoinId): bigint;
+}
+/**
+ * Async payment-data decoder matching the SDK's `decodePaymentData` signature.
+ * Used by `TokenSplit.split` (value conservation) and `SplitMintJustificationVerifier`.
+ */
+declare function decodeSpherePaymentData(bytes: Uint8Array): Promise<IPaymentData>;
+
+export { type CoinId, type CreateTokenEngine, type EngineConfig, type EngineIdentity, type EngineOpOptions, type EngineVerifyResult, type ITokenEngine, type IUnicityIdMinter, type MintDataTokenParams, type MintParams, type SphereAsset, type SphereNetwork, SpherePaymentData, type SphereToken, type SphereValue, type SplitOutput, type SplitParams, type SplitResult, type TokenBlob, type TransferParams, type UnicityIdMintResult, createSphereTokenEngine, createUnicityIdMinter, decodeSpherePaymentData, deriveDirectAddress, sphereAssetToSdk };