@unicitylabs/sphere-sdk 0.1.0

package/dist/impl/nodejs/index.d.ts

@@ -0,0 +1,1091 @@
+import { StateTransitionClient } from '@unicitylabs/state-transition-sdk/lib/StateTransitionClient';
+import { AggregatorClient } from '@unicitylabs/state-transition-sdk/lib/api/AggregatorClient';
+import { RootTrustBase } from '@unicitylabs/state-transition-sdk/lib/bft/RootTrustBase';
+import { TransferCommitment as TransferCommitment$1 } from '@unicitylabs/state-transition-sdk/lib/transaction/TransferCommitment';
+
+/**
+ * SDK2 Core Types
+ * Platform-independent type definitions
+ */
+type ProviderStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+interface ProviderMetadata {
+    readonly id: string;
+    readonly name: string;
+    readonly type: 'local' | 'cloud' | 'p2p' | 'network';
+    readonly description?: string;
+}
+interface BaseProvider extends ProviderMetadata {
+    connect(config?: unknown): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+}
+interface Identity {
+    readonly publicKey: string;
+    /** L1 address (alpha1...) */
+    readonly address: string;
+    /** L3 predicate address (DIRECT://...) */
+    readonly predicateAddress?: string;
+    readonly ipnsName?: string;
+    readonly nametag?: string;
+}
+interface FullIdentity extends Identity {
+    readonly privateKey: string;
+}
+
+/**
+ * Storage Provider Interface
+ * Platform-independent storage abstraction
+ */
+
+/**
+ * Basic key-value storage provider
+ * All operations are async for platform flexibility
+ */
+interface StorageProvider extends BaseProvider {
+    /**
+     * Set identity for scoped storage
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Get value by key
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set value by key
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Remove key
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Check if key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Get all keys with optional prefix filter
+     */
+    keys(prefix?: string): Promise<string[]>;
+    /**
+     * Clear all keys with optional prefix filter
+     */
+    clear(prefix?: string): Promise<void>;
+}
+/**
+ * Storage result types
+ */
+interface SaveResult {
+    success: boolean;
+    cid?: string;
+    error?: string;
+    timestamp: number;
+}
+interface LoadResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    source: 'local' | 'remote' | 'cache';
+    timestamp: number;
+}
+interface SyncResult<T = unknown> {
+    success: boolean;
+    merged?: T;
+    added: number;
+    removed: number;
+    conflicts: number;
+    error?: string;
+}
+/**
+ * Token-specific storage provider
+ * Handles token persistence with sync capabilities
+ */
+interface TokenStorageProvider<TData = unknown> extends BaseProvider {
+    /**
+     * Set identity for storage scope
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Initialize provider (called once after identity is set)
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * Shutdown provider
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Save token data
+     */
+    save(data: TData): Promise<SaveResult>;
+    /**
+     * Load token data
+     */
+    load(identifier?: string): Promise<LoadResult<TData>>;
+    /**
+     * Sync local data with remote
+     */
+    sync(localData: TData): Promise<SyncResult<TData>>;
+    /**
+     * Check if data exists
+     */
+    exists?(identifier?: string): Promise<boolean>;
+    /**
+     * Clear all data
+     */
+    clear?(): Promise<boolean>;
+    /**
+     * Subscribe to storage events
+     */
+    onEvent?(callback: StorageEventCallback): () => void;
+    /**
+     * Save individual token (for file-based storage like lottery pattern)
+     */
+    saveToken?(tokenId: string, tokenData: unknown): Promise<void>;
+    /**
+     * Get individual token
+     */
+    getToken?(tokenId: string): Promise<unknown | null>;
+    /**
+     * List all token IDs
+     */
+    listTokenIds?(): Promise<string[]>;
+    /**
+     * Delete individual token
+     */
+    deleteToken?(tokenId: string): Promise<void>;
+}
+type StorageEventType = 'storage:saving' | 'storage:saved' | 'storage:loading' | 'storage:loaded' | 'storage:error' | 'sync:started' | 'sync:completed' | 'sync:conflict' | 'sync:error';
+interface StorageEvent {
+    type: StorageEventType;
+    timestamp: number;
+    data?: unknown;
+    error?: string;
+}
+type StorageEventCallback = (event: StorageEvent) => void;
+interface TxfStorageDataBase {
+    _meta: TxfMeta;
+    _tombstones?: TxfTombstone[];
+    _outbox?: TxfOutboxEntry[];
+    _sent?: TxfSentEntry[];
+    _invalid?: TxfInvalidEntry[];
+    [key: `_${string}`]: unknown;
+}
+interface TxfMeta {
+    version: number;
+    address: string;
+    ipnsName?: string;
+    formatVersion: string;
+    updatedAt: number;
+}
+interface TxfTombstone {
+    tokenId: string;
+    stateHash: string;
+    timestamp: number;
+}
+interface TxfOutboxEntry {
+    id: string;
+    status: string;
+    tokenId: string;
+    recipient: string;
+    createdAt: number;
+    data: unknown;
+}
+interface TxfSentEntry {
+    tokenId: string;
+    recipient: string;
+    txHash: string;
+    sentAt: number;
+}
+interface TxfInvalidEntry {
+    tokenId: string;
+    reason: string;
+    detectedAt: number;
+}
+
+/**
+ * File Storage Provider for Node.js
+ * Stores wallet data in JSON files
+ */
+
+interface FileStorageProviderConfig {
+    /** Directory to store wallet data */
+    dataDir: string;
+    /** File name for key-value data (default: 'wallet.json') */
+    fileName?: string;
+}
+declare class FileStorageProvider implements StorageProvider {
+    readonly id = "file-storage";
+    readonly name = "File Storage";
+    readonly type: "local";
+    private dataDir;
+    private filePath;
+    private data;
+    private status;
+    private _identity;
+    constructor(config: FileStorageProviderConfig | string);
+    setIdentity(identity: FullIdentity): void;
+    getIdentity(): FullIdentity | null;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    keys(prefix?: string): Promise<string[]>;
+    clear(prefix?: string): Promise<void>;
+    private save;
+}
+declare function createFileStorageProvider(config: FileStorageProviderConfig | string): FileStorageProvider;
+
+/**
+ * File Token Storage Provider for Node.js
+ * Stores tokens as individual JSON files
+ */
+
+interface FileTokenStorageConfig {
+    /** Directory to store token files */
+    tokensDir: string;
+}
+declare class FileTokenStorageProvider implements TokenStorageProvider<TxfStorageDataBase> {
+    readonly id = "file-token-storage";
+    readonly name = "File Token Storage";
+    readonly type: "local";
+    private tokensDir;
+    private status;
+    private identity;
+    constructor(config: FileTokenStorageConfig | string);
+    setIdentity(identity: FullIdentity): void;
+    initialize(): Promise<boolean>;
+    shutdown(): Promise<void>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    load(): Promise<LoadResult<TxfStorageDataBase>>;
+    save(data: TxfStorageDataBase): Promise<SaveResult>;
+    sync(localData: TxfStorageDataBase): Promise<SyncResult<TxfStorageDataBase>>;
+    deleteToken(tokenId: string): Promise<void>;
+    saveToken(tokenId: string, tokenData: unknown): Promise<void>;
+    getToken(tokenId: string): Promise<unknown | null>;
+    listTokenIds(): Promise<string[]>;
+}
+declare function createFileTokenStorageProvider(config: FileTokenStorageConfig | string): FileTokenStorageProvider;
+
+/**
+ * Transport Provider Interface
+ * Platform-independent P2P messaging abstraction
+ */
+
+/**
+ * P2P messaging transport provider
+ */
+interface TransportProvider extends BaseProvider {
+    /**
+     * Set identity for signing/encryption
+     */
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Send encrypted direct message
+     * @returns Event ID
+     */
+    sendMessage(recipientPubkey: string, content: string): Promise<string>;
+    /**
+     * Subscribe to incoming direct messages
+     * @returns Unsubscribe function
+     */
+    onMessage(handler: MessageHandler): () => void;
+    /**
+     * Send token transfer payload
+     * @returns Event ID
+     */
+    sendTokenTransfer(recipientPubkey: string, payload: TokenTransferPayload): Promise<string>;
+    /**
+     * Subscribe to incoming token transfers
+     * @returns Unsubscribe function
+     */
+    onTokenTransfer(handler: TokenTransferHandler): () => void;
+    /**
+     * Resolve nametag to public key
+     */
+    resolveNametag?(nametag: string): Promise<string | null>;
+    /**
+     * Register a nametag for this identity
+     * @returns true if successful, false if already taken
+     */
+    registerNametag?(nametag: string, publicKey: string): Promise<boolean>;
+    /**
+     * Publish nametag binding
+     */
+    publishNametag?(nametag: string, address: string): Promise<void>;
+    /**
+     * Subscribe to broadcast messages (global/channel)
+     */
+    subscribeToBroadcast?(tags: string[], handler: BroadcastHandler): () => void;
+    /**
+     * Publish broadcast message
+     */
+    publishBroadcast?(content: string, tags?: string[]): Promise<string>;
+    /**
+     * Send payment request to a recipient
+     * @returns Event ID
+     */
+    sendPaymentRequest?(recipientPubkey: string, request: PaymentRequestPayload): Promise<string>;
+    /**
+     * Subscribe to incoming payment requests
+     * @returns Unsubscribe function
+     */
+    onPaymentRequest?(handler: PaymentRequestHandler): () => void;
+    /**
+     * Send response to a payment request
+     * @returns Event ID
+     */
+    sendPaymentRequestResponse?(recipientPubkey: string, response: PaymentRequestResponsePayload): Promise<string>;
+    /**
+     * Subscribe to incoming payment request responses
+     * @returns Unsubscribe function
+     */
+    onPaymentRequestResponse?(handler: PaymentRequestResponseHandler): () => void;
+    /**
+     * Get list of configured relay URLs
+     */
+    getRelays?(): string[];
+    /**
+     * Get list of currently connected relay URLs
+     */
+    getConnectedRelays?(): string[];
+    /**
+     * Add a relay dynamically
+     * @returns true if added successfully
+     */
+    addRelay?(relayUrl: string): Promise<boolean>;
+    /**
+     * Remove a relay dynamically
+     * @returns true if removed successfully
+     */
+    removeRelay?(relayUrl: string): Promise<boolean>;
+    /**
+     * Check if a relay is configured
+     */
+    hasRelay?(relayUrl: string): boolean;
+    /**
+     * Check if a relay is currently connected
+     */
+    isRelayConnected?(relayUrl: string): boolean;
+}
+interface IncomingMessage {
+    id: string;
+    senderPubkey: string;
+    content: string;
+    timestamp: number;
+    encrypted: boolean;
+}
+type MessageHandler = (message: IncomingMessage) => void;
+interface TokenTransferPayload {
+    /** Serialized token data */
+    token: string;
+    /** Inclusion proof */
+    proof: unknown;
+    /** Optional memo */
+    memo?: string;
+    /** Sender info */
+    sender?: {
+        pubkey: string;
+        nametag?: string;
+    };
+}
+interface IncomingTokenTransfer {
+    id: string;
+    senderPubkey: string;
+    payload: TokenTransferPayload;
+    timestamp: number;
+}
+type TokenTransferHandler = (transfer: IncomingTokenTransfer) => void;
+interface PaymentRequestPayload {
+    /** Amount requested (in smallest units) */
+    amount: string | bigint;
+    /** Coin/token type ID */
+    coinId: string;
+    /** Message/memo for recipient */
+    message?: string;
+    /** Recipient's nametag (who should pay) */
+    recipientNametag?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+interface IncomingPaymentRequest {
+    /** Event ID */
+    id: string;
+    /** Sender's public key */
+    senderPubkey: string;
+    /** Parsed request data */
+    request: {
+        requestId: string;
+        amount: string;
+        coinId: string;
+        message?: string;
+        recipientNametag?: string;
+        metadata?: Record<string, unknown>;
+    };
+    /** Timestamp */
+    timestamp: number;
+}
+type PaymentRequestHandler = (request: IncomingPaymentRequest) => void;
+type PaymentRequestResponseType = 'accepted' | 'rejected' | 'paid';
+interface PaymentRequestResponsePayload {
+    /** Original request ID */
+    requestId: string;
+    /** Response type */
+    responseType: PaymentRequestResponseType;
+    /** Optional message */
+    message?: string;
+    /** Transfer ID (if paid) */
+    transferId?: string;
+}
+interface IncomingPaymentRequestResponse {
+    /** Event ID */
+    id: string;
+    /** Responder's public key */
+    responderPubkey: string;
+    /** Parsed response data */
+    response: {
+        requestId: string;
+        responseType: PaymentRequestResponseType;
+        message?: string;
+        transferId?: string;
+    };
+    /** Timestamp */
+    timestamp: number;
+}
+type PaymentRequestResponseHandler = (response: IncomingPaymentRequestResponse) => void;
+interface IncomingBroadcast {
+    id: string;
+    authorPubkey: string;
+    content: string;
+    tags: string[];
+    timestamp: number;
+}
+type BroadcastHandler = (broadcast: IncomingBroadcast) => void;
+type TransportEventType = 'transport:connected' | 'transport:disconnected' | 'transport:reconnecting' | 'transport:error' | 'transport:relay_added' | 'transport:relay_removed' | 'message:received' | 'message:sent' | 'transfer:received' | 'transfer:sent';
+interface TransportEvent {
+    type: TransportEventType;
+    timestamp: number;
+    data?: unknown;
+    error?: string;
+}
+type TransportEventCallback = (event: TransportEvent) => void;
+
+/**
+ * WebSocket Abstraction
+ * Platform-independent WebSocket interface for cross-platform support
+ */
+/**
+ * Minimal WebSocket interface compatible with browser and Node.js
+ */
+interface IWebSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onmessage: ((event: IMessageEvent) => void) | null;
+}
+interface IMessageEvent {
+    data: string;
+}
+/**
+ * Factory function to create WebSocket instances
+ * Different implementations for browser (native) vs Node.js (ws package)
+ */
+type WebSocketFactory = (url: string) => IWebSocket;
+/**
+ * Generate a unique ID (platform-independent)
+ * Browser: crypto.randomUUID()
+ * Node: crypto.randomUUID() or uuid package
+ */
+type UUIDGenerator = () => string;
+
+/**
+ * Nostr Transport Provider
+ * Platform-independent implementation using Nostr protocol for P2P messaging
+ *
+ * Uses @unicitylabs/nostr-js-sdk for:
+ * - Real secp256k1 event signing
+ * - NIP-04 encryption/decryption
+ * - Event ID calculation
+ *
+ * WebSocket is injected via factory for cross-platform support
+ */
+
+interface NostrTransportProviderConfig {
+    /** Nostr relay URLs */
+    relays?: string[];
+    /** Connection timeout (ms) */
+    timeout?: number;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Reconnect delay (ms) */
+    reconnectDelay?: number;
+    /** Max reconnect attempts */
+    maxReconnectAttempts?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** WebSocket factory (required for platform support) */
+    createWebSocket: WebSocketFactory;
+    /** UUID generator (optional, defaults to crypto.randomUUID) */
+    generateUUID?: UUIDGenerator;
+}
+declare class NostrTransportProvider implements TransportProvider {
+    readonly id = "nostr";
+    readonly name = "Nostr Transport";
+    readonly type: "p2p";
+    readonly description = "P2P messaging via Nostr protocol";
+    private config;
+    private identity;
+    private keyManager;
+    private status;
+    private connections;
+    private reconnectAttempts;
+    private messageHandlers;
+    private transferHandlers;
+    private paymentRequestHandlers;
+    private paymentRequestResponseHandlers;
+    private broadcastHandlers;
+    private eventCallbacks;
+    private subscriptions;
+    constructor(config: NostrTransportProviderConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    /**
+     * Get list of configured relay URLs
+     */
+    getRelays(): string[];
+    /**
+     * Get list of currently connected relay URLs
+     */
+    getConnectedRelays(): string[];
+    /**
+     * Add a new relay dynamically
+     * Will connect immediately if provider is already connected
+     */
+    addRelay(relayUrl: string): Promise<boolean>;
+    /**
+     * Remove a relay dynamically
+     * Will disconnect from the relay if connected
+     */
+    removeRelay(relayUrl: string): Promise<boolean>;
+    /**
+     * Check if a relay is configured
+     */
+    hasRelay(relayUrl: string): boolean;
+    /**
+     * Check if a relay is currently connected
+     */
+    isRelayConnected(relayUrl: string): boolean;
+    setIdentity(identity: FullIdentity): void;
+    /**
+     * Get the Nostr-format public key (32 bytes / 64 hex chars)
+     * This is the x-coordinate only, without the 02/03 prefix.
+     */
+    getNostrPubkey(): string;
+    sendMessage(recipientPubkey: string, content: string): Promise<string>;
+    onMessage(handler: MessageHandler): () => void;
+    sendTokenTransfer(recipientPubkey: string, payload: TokenTransferPayload): Promise<string>;
+    onTokenTransfer(handler: TokenTransferHandler): () => void;
+    sendPaymentRequest(recipientPubkey: string, payload: PaymentRequestPayload): Promise<string>;
+    onPaymentRequest(handler: PaymentRequestHandler): () => void;
+    sendPaymentRequestResponse(recipientPubkey: string, payload: PaymentRequestResponsePayload): Promise<string>;
+    onPaymentRequestResponse(handler: PaymentRequestResponseHandler): () => void;
+    resolveNametag(nametag: string): Promise<string | null>;
+    publishNametag(nametag: string, address: string): Promise<void>;
+    registerNametag(nametag: string, _publicKey: string): Promise<boolean>;
+    subscribeToBroadcast(tags: string[], handler: BroadcastHandler): () => void;
+    publishBroadcast(content: string, tags?: string[]): Promise<string>;
+    onEvent(callback: TransportEventCallback): () => void;
+    private connectToRelay;
+    private scheduleReconnect;
+    private handleRelayMessage;
+    private handleEvent;
+    private handleDirectMessage;
+    private handleTokenTransfer;
+    private handlePaymentRequest;
+    private handlePaymentRequestResponse;
+    private handleBroadcast;
+    private createEvent;
+    private createEncryptedEvent;
+    private publishEvent;
+    private queryEvents;
+    private queryEventsFromRelay;
+    private unsubscribeFromRelay;
+    private subscribeToEvents;
+    private subscribeToTags;
+    private decryptContent;
+    /**
+     * Strip known content prefixes (nostr-js-sdk compatibility)
+     * Handles: payment_request:, token_transfer:, etc.
+     */
+    private stripContentPrefix;
+    private ensureReady;
+    private emitEvent;
+    private log;
+}
+
+/**
+ * Node.js Transport Exports
+ * Re-exports shared transport with Node.js WebSocket
+ */
+
+/**
+ * Create WebSocket factory for Node.js using 'ws' package
+ */
+declare function createNodeWebSocketFactory(): WebSocketFactory;
+/**
+ * Create NostrTransportProvider with Node.js WebSocket
+ */
+declare function createNostrTransportProvider(config: Omit<NostrTransportProviderConfig, 'createWebSocket'>): NostrTransportProvider;
+
+/**
+ * Oracle Provider Interface
+ * Platform-independent Unicity oracle abstraction
+ *
+ * The oracle is a trusted third-party service that provides verifiable truth
+ * about the state of tokens in the Unicity network. It aggregates state
+ * transitions into rounds and provides inclusion proofs that cryptographically
+ * verify token ownership and transfers.
+ */
+
+/**
+ * Unicity state transition oracle provider
+ *
+ * The oracle serves as the source of truth for:
+ * - Token state validation (spent/unspent)
+ * - State transition inclusion proofs
+ * - Round-based commitment aggregation
+ */
+interface OracleProvider extends BaseProvider {
+    /**
+     * Initialize with trust base
+     */
+    initialize(trustBase?: unknown): Promise<void>;
+    /**
+     * Submit transfer commitment
+     */
+    submitCommitment(commitment: TransferCommitment): Promise<SubmitResult>;
+    /**
+     * Get inclusion proof for a request
+     */
+    getProof(requestId: string): Promise<InclusionProof | null>;
+    /**
+     * Wait for inclusion proof with polling
+     */
+    waitForProof(requestId: string, options?: WaitOptions): Promise<InclusionProof>;
+    /**
+     * Validate token against aggregator
+     */
+    validateToken(tokenData: unknown): Promise<ValidationResult>;
+    /**
+     * Check if token state is spent
+     */
+    isSpent(stateHash: string): Promise<boolean>;
+    /**
+     * Get token state
+     */
+    getTokenState(tokenId: string): Promise<TokenState | null>;
+    /**
+     * Get current round number
+     */
+    getCurrentRound(): Promise<number>;
+    /**
+     * Mint new tokens (for faucet/testing)
+     */
+    mint?(params: MintParams): Promise<MintResult>;
+    /**
+     * Get underlying StateTransitionClient (if available)
+     * Used for advanced SDK operations like commitment creation
+     */
+    getStateTransitionClient?(): unknown;
+    /**
+     * Get underlying AggregatorClient (if available)
+     * Used for direct aggregator API access
+     */
+    getAggregatorClient?(): unknown;
+    /**
+     * Wait for inclusion proof using SDK commitment (if available)
+     * Used for transfer flows with SDK TransferCommitment
+     */
+    waitForProofSdk?(commitment: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+interface TransferCommitment {
+    /** Source token (SDK format) */
+    sourceToken: unknown;
+    /** Recipient address/predicate */
+    recipient: string;
+    /** Random salt (non-reproducible) */
+    salt: Uint8Array;
+    /** Optional additional data */
+    data?: unknown;
+}
+interface SubmitResult {
+    success: boolean;
+    requestId?: string;
+    error?: string;
+    timestamp: number;
+}
+interface InclusionProof {
+    requestId: string;
+    roundNumber: number;
+    proof: unknown;
+    timestamp: number;
+}
+interface WaitOptions {
+    /** Timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Poll interval in ms (default: 1000) */
+    pollInterval?: number;
+    /** Callback on each poll attempt */
+    onPoll?: (attempt: number) => void;
+}
+interface ValidationResult {
+    valid: boolean;
+    spent: boolean;
+    error?: string;
+    stateHash?: string;
+}
+interface TokenState {
+    tokenId: string;
+    stateHash: string;
+    spent: boolean;
+    roundNumber?: number;
+    lastUpdated: number;
+}
+interface MintParams {
+    coinId: string;
+    amount: string;
+    recipientAddress: string;
+    recipientPubkey?: string;
+}
+interface MintResult {
+    success: boolean;
+    requestId?: string;
+    tokenId?: string;
+    error?: string;
+}
+type OracleEventType = 'oracle:connected' | 'oracle:disconnected' | 'oracle:error' | 'commitment:submitted' | 'proof:received' | 'validation:completed';
+interface OracleEvent {
+    type: OracleEventType;
+    timestamp: number;
+    data?: unknown;
+    error?: string;
+}
+type OracleEventCallback = (event: OracleEvent) => void;
+/**
+ * Trust base loader interface for platform-specific loading
+ * Browser: fetch from URL
+ * Node.js: read from file
+ */
+interface TrustBaseLoader {
+    /**
+     * Load trust base JSON data
+     * @returns Trust base data or null if not available
+     */
+    load(): Promise<unknown | null>;
+}
+
+/**
+ * Unicity Aggregator Provider
+ * Platform-independent implementation using @unicitylabs/state-transition-sdk
+ *
+ * The oracle is a trusted service that provides verifiable truth
+ * about token state through cryptographic inclusion proofs.
+ *
+ * TrustBaseLoader is injected for platform-specific loading:
+ * - Browser: fetch from URL
+ * - Node.js: read from file
+ */
+
+interface SdkMintCommitment {
+    requestId?: {
+        toString(): string;
+    };
+    [key: string]: unknown;
+}
+interface UnicityAggregatorProviderConfig {
+    /** Aggregator URL */
+    url: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Request timeout (ms) */
+    timeout?: number;
+    /** Skip trust base verification (dev only) */
+    skipVerification?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Trust base loader (platform-specific) */
+    trustBaseLoader?: TrustBaseLoader;
+}
+/**
+ * Unicity Aggregator Provider
+ * Concrete implementation of OracleProvider using Unicity's aggregator service
+ */
+declare class UnicityAggregatorProvider implements OracleProvider {
+    readonly id = "unicity-aggregator";
+    readonly name = "Unicity Aggregator";
+    readonly type: "network";
+    readonly description = "Unicity state transition aggregator (oracle implementation)";
+    private config;
+    private status;
+    private eventCallbacks;
+    private aggregatorClient;
+    private stateTransitionClient;
+    private trustBase;
+    /** Get the current trust base */
+    getTrustBase(): RootTrustBase | null;
+    /** Get the state transition client */
+    getStateTransitionClient(): StateTransitionClient | null;
+    /** Get the aggregator client */
+    getAggregatorClient(): AggregatorClient | null;
+    private spentCache;
+    constructor(config: UnicityAggregatorProviderConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ProviderStatus;
+    initialize(trustBase?: RootTrustBase): Promise<void>;
+    /**
+     * Submit a transfer commitment to the aggregator.
+     * Accepts either an SDK TransferCommitment or a simple commitment object.
+     */
+    submitCommitment(commitment: TransferCommitment | TransferCommitment$1): Promise<SubmitResult>;
+    /**
+     * Submit a mint commitment to the aggregator (SDK only)
+     * @param commitment - SDK MintCommitment instance
+     */
+    submitMintCommitment(commitment: SdkMintCommitment): Promise<SubmitResult>;
+    private isSdkTransferCommitment;
+    getProof(requestId: string): Promise<InclusionProof | null>;
+    waitForProof(requestId: string, options?: WaitOptions): Promise<InclusionProof>;
+    validateToken(tokenData: unknown): Promise<ValidationResult>;
+    /**
+     * Wait for inclusion proof using SDK (for SDK commitments)
+     */
+    waitForProofSdk(commitment: TransferCommitment$1 | SdkMintCommitment, signal?: AbortSignal): Promise<unknown>;
+    isSpent(stateHash: string): Promise<boolean>;
+    getTokenState(tokenId: string): Promise<TokenState | null>;
+    getCurrentRound(): Promise<number>;
+    mint(params: MintParams): Promise<MintResult>;
+    onEvent(callback: OracleEventCallback): () => void;
+    private rpcCall;
+    private ensureConnected;
+    private emitEvent;
+    private log;
+}
+/** @deprecated Use UnicityAggregatorProvider instead */
+declare const UnicityOracleProvider: typeof UnicityAggregatorProvider;
+/** @deprecated Use UnicityAggregatorProviderConfig instead */
+type UnicityOracleProviderConfig = UnicityAggregatorProviderConfig;
+
+/**
+ * Node.js Oracle Exports
+ * Re-exports shared oracle with Node.js-specific TrustBaseLoader
+ */
+
+/**
+ * Node.js TrustBase loader using fs
+ */
+declare class NodeTrustBaseLoader implements TrustBaseLoader {
+    private filePath;
+    constructor(filePath?: string);
+    load(): Promise<unknown | null>;
+}
+/**
+ * Create Node.js TrustBase loader
+ */
+declare function createNodeTrustBaseLoader(filePath?: string): TrustBaseLoader;
+/**
+ * Create UnicityAggregatorProvider with Node.js TrustBase loader
+ */
+declare function createUnicityAggregatorProvider(config: Omit<UnicityAggregatorProviderConfig, 'trustBaseLoader'> & {
+    trustBasePath?: string;
+}): UnicityAggregatorProvider;
+/** @deprecated Use createUnicityAggregatorProvider instead */
+declare const createUnicityOracleProvider: typeof createUnicityAggregatorProvider;
+
+/** Network configurations */
+declare const NETWORKS: {
+    readonly mainnet: {
+        readonly name: "Mainnet";
+        readonly aggregatorUrl: "https://aggregator.unicity.network/rpc";
+        readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
+        readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
+        readonly electrumUrl: "wss://fulcrum.alpha.unicity.network:50004";
+    };
+    readonly testnet: {
+        readonly name: "Testnet";
+        readonly aggregatorUrl: "https://goggregator-test.unicity.network";
+        readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
+        readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
+        readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+    };
+    readonly dev: {
+        readonly name: "Development";
+        readonly aggregatorUrl: "https://dev-aggregator.dyndns.org/rpc";
+        readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
+        readonly ipfsGateways: readonly ["https://ipfs.unicity.network", "https://dweb.link", "https://ipfs.io"];
+        readonly electrumUrl: "wss://fulcrum.alpha.testnet.unicity.network:50004";
+    };
+};
+type NetworkType = keyof typeof NETWORKS;
+
+/**
+ * Shared Configuration Interfaces
+ * Base types extended by platform-specific implementations
+ */
+
+/**
+ * Base transport (Nostr) configuration
+ * Supports extend/override pattern for relays
+ */
+interface BaseTransportConfig {
+    /** Replace default relays entirely */
+    relays?: string[];
+    /** Add relays to network defaults (use with network preset) */
+    additionalRelays?: string[];
+    /** Connection timeout (ms) */
+    timeout?: number;
+    /** Auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Base oracle (Aggregator) configuration
+ */
+interface BaseOracleConfig {
+    /** Replace default aggregator URL (if not set, uses network default) */
+    url?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Request timeout (ms) */
+    timeout?: number;
+    /** Skip trust base verification (dev only) */
+    skipVerification?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Node.js-specific oracle extensions
+ */
+interface NodeOracleExtensions {
+    /** Path to trust base JSON file */
+    trustBasePath?: string;
+}
+/**
+ * L1 (ALPHA blockchain) configuration
+ * Same for all platforms
+ */
+interface L1Config {
+    /** Fulcrum WebSocket URL (if not set, uses network default) */
+    electrumUrl?: string;
+    /** Default fee rate in sat/byte */
+    defaultFeeRate?: number;
+    /** Enable vesting classification */
+    enableVesting?: boolean;
+}
+/**
+ * Base providers result
+ * Common structure for all platforms
+ */
+interface BaseProviders {
+    storage: StorageProvider;
+    tokenStorage: TokenStorageProvider<TxfStorageDataBase>;
+    transport: TransportProvider;
+    oracle: OracleProvider;
+    /** L1 configuration (for passing to Sphere.init) */
+    l1?: L1Config;
+}
+
+/**
+ * Node.js Implementation
+ * Providers for CLI/Node.js usage
+ */
+
+/**
+ * Node.js transport configuration
+ * Same as base (no Node.js-specific extensions)
+ */
+type NodeTransportConfig = BaseTransportConfig;
+/**
+ * Node.js oracle configuration
+ * Extends base with trustBasePath for file-based trust base
+ */
+type NodeOracleConfig = BaseOracleConfig & NodeOracleExtensions;
+/**
+ * Node.js L1 configuration
+ * Same as base
+ */
+type NodeL1Config = L1Config;
+interface NodeProvidersConfig {
+    /** Network preset: mainnet, testnet, or dev */
+    network?: NetworkType;
+    /** Directory for wallet data storage */
+    dataDir?: string;
+    /** Directory for token files */
+    tokensDir?: string;
+    /** Transport (Nostr) configuration */
+    transport?: NodeTransportConfig;
+    /** Oracle (Aggregator) configuration */
+    oracle?: NodeOracleConfig;
+    /** L1 (ALPHA blockchain) configuration */
+    l1?: NodeL1Config;
+}
+interface NodeProviders {
+    storage: StorageProvider;
+    tokenStorage: TokenStorageProvider<TxfStorageDataBase>;
+    transport: TransportProvider;
+    oracle: OracleProvider;
+    /** L1 configuration (for passing to Sphere.init) */
+    l1?: L1Config;
+}
+/**
+ * Create all Node.js providers with default configuration
+ *
+ * @example
+ * ```ts
+ * // Simple - testnet with defaults
+ * const providers = createNodeProviders({
+ *   network: 'testnet',
+ *   tokensDir: './tokens',
+ * });
+ *
+ * // Full configuration
+ * const providers = createNodeProviders({
+ *   network: 'testnet',
+ *   dataDir: './wallet-data',
+ *   tokensDir: './tokens',
+ *   transport: {
+ *     additionalRelays: ['wss://my-relay.com'],
+ *     debug: true,
+ *   },
+ *   oracle: {
+ *     apiKey: 'my-api-key',
+ *     trustBasePath: './trustbase.json',
+ *   },
+ *   l1: {
+ *     enableVesting: true,
+ *   },
+ * });
+ *
+ * // Use with Sphere.init
+ * const { sphere } = await Sphere.init({
+ *   ...providers,
+ *   autoGenerate: true,
+ * });
+ * ```
+ */
+declare function createNodeProviders(config?: NodeProvidersConfig): NodeProviders;
+
+export { type BaseOracleConfig, type BaseProviders, type BaseTransportConfig, FileStorageProvider, type FileStorageProviderConfig, type FileTokenStorageConfig, FileTokenStorageProvider, type IWebSocket, type L1Config, type NodeL1Config, type NodeOracleConfig, type NodeProviders, type NodeProvidersConfig, type NodeTransportConfig, NodeTrustBaseLoader, NostrTransportProvider, type NostrTransportProviderConfig, type TrustBaseLoader, UnicityAggregatorProvider, type UnicityAggregatorProviderConfig, UnicityOracleProvider, type UnicityOracleProviderConfig, type WebSocketFactory, createFileStorageProvider, createFileTokenStorageProvider, createNodeProviders, createNodeTrustBaseLoader, createNodeWebSocketFactory, createNostrTransportProvider, createUnicityAggregatorProvider, createUnicityOracleProvider };