@0xio/sdk 2.7.0 → 2.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * 0xio SDK — Wallet Transport Adapter Interface
+ * 0xio SDK: Wallet Transport Adapter Interface
  *
  * Implement WalletTransportAdapter to add support for a new wallet without
  * touching any core SDK code. Drop the adapter file in src/supports/ and
@@ -17,7 +17,7 @@
  * ```
  */
 /**
- * Outbound request — the SDK passes this to adapter.postRequest() for every
+ * Outbound request: the SDK passes this to adapter.postRequest() for every
  * outbound wallet call. Adapters translate this into their wallet-specific wire format.
  */
 interface AdapterRequest {
@@ -63,8 +63,8 @@ interface AdapterIncomingMessage {
  * - How to send requests (postRequest)
  * - How to receive responses and events (listen)
  *
- * Everything else — request lifecycle, timeouts, retries, rate limiting,
- * event routing — is handled by the SDK core and does not change per wallet.
+ * Everything else (request lifecycle, timeouts, retries, rate limiting,
+ * event routing) is handled by the SDK core and does not change per wallet.
  *
  * @example Minimal adapter for a hypothetical wallet
  * ```typescript
@@ -103,7 +103,7 @@ interface WalletTransportAdapter {
     detect(): boolean;
     /**
      * Send a request to the wallet.
-     * Called once per outbound request — translate AdapterRequest into your
+     * Called once per outbound request: translate AdapterRequest into your
      * wallet's wire format and post it (window.postMessage, direct API call, etc.).
      */
     postRequest(request: AdapterRequest): void;
@@ -120,7 +120,7 @@ interface WalletTransportAdapter {
      *
      * @param handler  Callback for responses and push events
      * @param options  SDK-level options, e.g. additional trusted parent origins
-     * @returns        A teardown function — the SDK calls it on cleanup()
+     * @returns        A teardown function. The SDK calls it on cleanup()
      */
     listen(handler: (msg: AdapterIncomingMessage) => void, options?: {
         trustedParentOrigins?: string[];
@@ -162,16 +162,21 @@ interface NetworkInfo {
 }
 interface TransactionData {
     readonly to: string;
-    /** Amount in OCT. Accepts string or number — use string for amounts above 9 billion OCT to avoid JS number precision loss. */
-    readonly amount: string | number;
+    /**
+     * Raw amount in micro-OCT (1 OCT = 1000000), passed to the wallet unchanged. This is what
+     * the wallet and the RFC-O-1 provider expect. Prefer `amountOct` when you think in OCT.
+     */
+    readonly amount?: string | number;
+    /** Amount in OCT. The SDK converts it to raw units exactly (at most 6 decimals). Use this or `amount`, not both. */
+    readonly amountOct?: string | number;
     readonly message?: string;
     readonly feeLevel?: 1 | 3;
     readonly isPrivate?: boolean;
 }
 /**
- * Contract method arguments — flat array of AML-compatible values.
+ * Contract method arguments: flat array of AML-compatible values.
  * Supports primitives and base64-encoded binary data (e.g. FHE ciphers, proofs).
- * Use `[arg1, arg2]` NOT `[[arg1, arg2]]` — flat, not nested.
+ * Use `[arg1, arg2]`, not `[[arg1, arg2]]`: flat, not nested.
  */
 type ContractParam = string | number | boolean;
 type ContractParams = ReadonlyArray<ContractParam>;
@@ -181,16 +186,18 @@ interface ContractCallData {
     /** Contract method name (e.g. 'swap', 'open_private_account') */
     readonly method: string;
     /**
-     * Method arguments — flat primitives, NOT array-wrapped.
+     * Method arguments: flat primitives, not array-wrapped.
      * For FHE/PVAC operations, encode binary data as base64 strings:
      * `[base64(pvacPubkey), base64(zeroCipher), base64(zeroProof)]`
      */
     readonly params: ContractParams;
     /**
-     * Native OCT to send with the call (in micro-units, 1 OCT = 1000000).
-     * Set to 0 for calls that don't transfer native tokens.
+     * Native value to attach, in raw micro-OCT (1 OCT = 1000000), passed to the wallet unchanged.
+     * Omit or set '0' for calls that transfer nothing. Prefer `amountOct` when you think in OCT.
      */
     readonly amount?: string | number;
+    /** Value to attach in OCT. The SDK converts it to raw units exactly. Use this or `amount`, not both. */
+    readonly amountOct?: string | number;
     /**
      * Operation units / gas limit (default: 10000).
      * Higher values for complex contract operations.
@@ -203,7 +210,7 @@ interface ContractViewCallData {
     readonly contract: string;
     /** Contract method name (e.g. 'balance_of', 'get_active_bin', 'is_paused') */
     readonly method: string;
-    /** Method arguments — flat primitives, NOT array-wrapped */
+    /** Method arguments: flat primitives, not array-wrapped */
     readonly params: ContractParams;
     /** Caller address for view context (defaults to connected wallet) */
     readonly caller?: string;
@@ -221,8 +228,16 @@ interface SignedTransaction {
 }
 type TransactionFinality = 'pending' | 'confirmed' | 'rejected' | 'dropped';
 interface TransactionResult {
-    readonly txHash: string;
-    readonly success: boolean;
+    /** RFC-O-1 canonical hash field */
+    readonly hash?: string;
+    /** RFC-O-1 canonical accepted field */
+    readonly accepted?: boolean;
+    /** RFC-O-1 status field */
+    readonly status?: TransactionFinality;
+    /** @deprecated Use hash */
+    readonly txHash?: string;
+    /** @deprecated Use accepted */
+    readonly success?: boolean;
     readonly finality?: TransactionFinality;
     readonly message?: string;
     readonly explorerUrl?: string;
@@ -237,7 +252,7 @@ interface Transaction {
     readonly hash: string;
     readonly from: string;
     readonly to: string;
-    /** Amount in OCT as returned by the node (may be string or number depending on extension version). */
+    /** Amount in raw micro-OCT as returned by the node (string or number depending on the wallet version). */
     readonly amount: string | number;
     /** Fee in OCT as returned by the node (may be string or number depending on extension version). */
     readonly fee: string | number;
@@ -257,11 +272,14 @@ interface ConnectionInfo {
     permissions?: Permission[];
 }
 interface ConnectOptions {
+    /** RFC-O-1 canonical field name */
+    readonly permissions?: Permission[];
+    /** @deprecated Use permissions */
     readonly requestPermissions?: Permission[];
     readonly networkId?: string;
 }
-type Permission = 'read_address' | 'read_balance' | 'send_transactions' | 'sign_messages' | 'view_private_balance' | 'private_transfers';
-type WalletEventType = 'connect' | 'disconnect' | 'accountChanged' | 'balanceChanged' | 'networkChanged' | 'transactionConfirmed' | 'error' | 'extensionLocked' | 'extensionUnlocked';
+type Permission = 'accounts' | 'public_transactions' | 'contract_views' | 'private_balance_read' | 'private_proofs' | 'private_claims' | 'read_address' | 'read_balance' | 'read_public_key' | 'send_transactions' | 'sign_messages' | 'contract_calls' | 'view_private_balance' | 'view_encrypted_balance' | 'private_transfers' | 'encrypt_balance' | 'decrypt_balance' | 'stealth_scan' | 'stealth_claim';
+type WalletEventType = 'connect' | 'disconnect' | 'accountChanged' | 'balanceChanged' | 'networkChanged' | 'transactionConfirmed' | 'transactionFailed' | 'permissionsChanged' | 'message' | 'error' | 'extensionLocked' | 'extensionUnlocked';
 interface WalletEvent<T = any> {
     readonly type: WalletEventType;
     readonly data: T;
@@ -320,7 +338,16 @@ declare enum ErrorCode {
     INVALID_SIGNATURE = "INVALID_SIGNATURE",
     DUPLICATE_TRANSACTION = "DUPLICATE_TRANSACTION",
     NONCE_TOO_FAR = "NONCE_TOO_FAR",
-    INTERNAL_ERROR = "INTERNAL_ERROR"
+    INTERNAL_ERROR = "INTERNAL_ERROR",
+    NOT_CONNECTED = "NOT_CONNECTED",
+    INVALID_PARAMS = "INVALID_PARAMS",
+    METHOD_NOT_ALLOWED = "METHOD_NOT_ALLOWED",
+    NOT_AVAILABLE = "NOT_AVAILABLE",
+    PRIVATE_PROOF_FAILED = "PRIVATE_PROOF_FAILED",
+    PRIVATE_TRANSFER_FAILED = "PRIVATE_TRANSFER_FAILED",
+    CONTRACT_CALL_FAILED = "CONTRACT_CALL_FAILED",
+    SIGN_FAILED = "SIGN_FAILED",
+    RECIPIENT_NOT_REGISTERED = "RECIPIENT_NOT_REGISTERED"
 }
 declare class ZeroXIOWalletError extends Error {
     readonly code: ErrorCode;
@@ -334,12 +361,21 @@ interface PrivateBalanceInfo {
 }
 interface PrivateTransferData {
     readonly to: string;
-    /** Amount in OCT. Accepts string or number — use string for amounts above 9 billion OCT to avoid JS number precision loss. */
+    /** Amount in OCT. Accepts string or number. Use string for amounts above 9 billion OCT to avoid JS number precision loss. */
     readonly amount: string | number;
+    /** Exact amount in raw micro-OCT. When set, it is what the wallet uses; `amount` is then display only. */
+    readonly amountRaw?: string;
+    /** Not carried by the wallet today; private transfers have no memo on-chain. */
     readonly message?: string;
 }
+/**
+ * A claimable stealth output as the wallet returns it. The 0xio extension fills `id` and
+ * `amount` (raw micro-OCT) from the node; the other fields depend on the wallet.
+ */
 interface PendingPrivateTransfer {
     readonly id: string;
+    /** Raw micro-OCT, when the wallet exposes the amount. */
+    readonly amount?: number | string;
     readonly from: string;
     readonly encryptedAmount: string;
     readonly message?: string;
@@ -355,6 +391,12 @@ interface SDKConfig {
     readonly requiredPermissions?: Permission[];
     readonly networkId?: string;
     readonly debug?: boolean;
+    /**
+     * Exact origins allowed as parent iframe bridge (e.g. 'https://app.example.com').
+     * When set, only these origins (plus tauri://) are trusted: implicit localhost trust
+     * is disabled. Leave unset for development (all localhost trusted by default).
+     */
+    readonly trustedParentOrigins?: string[];
     /**
      * Custom wallet transport adapter.
      * Defaults to ZeroXIOAdapter (0xio extension postMessage protocol).
@@ -384,55 +426,20 @@ interface ExtensionResponse<T = any> {
     readonly timestamp: number;
 }
 
-/**
- * 0xio Wallet SDK - Event System
- * Type-safe event emitter for wallet events
- */
-
 type EventListener<T = any> = (event: WalletEvent<T>) => void;
 declare class EventEmitter {
     private listeners;
-    private debug;
-    constructor(debug?: boolean);
-    /**
-     * Add event listener
-     */
+    constructor(_debug?: boolean);
     on<T = any>(eventType: WalletEventType, listener: EventListener<T>): void;
-    /**
-     * Remove event listener
-     */
     off<T = any>(eventType: WalletEventType, listener: EventListener<T>): void;
-    /**
-     * Add one-time event listener
-     */
     once<T = any>(eventType: WalletEventType, listener: EventListener<T>): void;
-    /**
-     * Emit event to all listeners
-     */
     emit<T = any>(eventType: WalletEventType, data: T): void;
-    /**
-     * Remove all listeners for a specific event type
-     */
     removeAllListeners(eventType?: WalletEventType): void;
-    /**
-     * Get number of listeners for an event type
-     */
     listenerCount(eventType: WalletEventType): number;
-    /**
-     * Get all event types that have listeners
-     */
     eventTypes(): WalletEventType[];
-    /**
-     * Check if there are any listeners for an event type
-     */
     hasListeners(eventType: WalletEventType): boolean;
 }
 
-/**
- * 0xio Wallet SDK - Main Wallet Class
- * Primary interface for DApp developers to interact with 0xio Wallet
- */
-
 declare class ZeroXIOWallet extends EventEmitter {
     private communicator;
     private config;
@@ -442,18 +449,8 @@ declare class ZeroXIOWallet extends EventEmitter {
     private _sessionVersion;
     private logger;
     constructor(config: SDKConfig);
-    /**
-     * Initialize the SDK
-     * Must be called before using any other methods
-     */
     initialize(): Promise<boolean>;
-    /**
-     * Check if SDK is initialized
-     */
     isReady(): boolean;
-    /**
-     * Connect to wallet
-     */
     connect(options?: ConnectOptions): Promise<ConnectEvent>;
     /**
      * Disconnect from wallet
@@ -472,8 +469,8 @@ declare class ZeroXIOWallet extends EventEmitter {
      */
     getConnectionStatus(): Promise<ConnectionInfo>;
     /**
-     * Switch the extension's active network (e.g. 'mainnet' → 'devnet').
-     * Works silently — no popup, no user confirmation needed.
+     * Switch the extension's active network (e.g. 'mainnet' to 'devnet').
+     * Works silently: no popup, no user confirmation needed.
      * The extension broadcasts 'networkChanged' event to all connected dApps.
      */
     switchNetwork(networkId: string): Promise<{
@@ -484,22 +481,27 @@ declare class ZeroXIOWallet extends EventEmitter {
      * Get the extension's current network ID ('mainnet' or 'devnet')
      */
     getNetworkId(): string | null;
-    /**
-     * Get current wallet address
-     */
     getAddress(): string | null;
     /**
-     * Get current balance
+     * The connected account's Ed25519 public key (base64). Served from the session when the
+     * wallet reported it at connect, otherwise asked from the wallet.
      */
+    getPublicKey(): Promise<string>;
     getBalance(forceRefresh?: boolean): Promise<Balance>;
+    getNetworkInfo(): Promise<NetworkInfo>;
+    sendTransaction(txData: TransactionData): Promise<TransactionResult>;
     /**
-     * Get network information
+     * Sign a transaction without broadcasting it (RFC-O-1 octra_signTransaction).
+     * Returns the signed transaction object for manual submission via submitTransaction().
      */
-    getNetworkInfo(): Promise<NetworkInfo>;
+    signTransaction(txData: TransactionData): Promise<{
+        signedTx: any;
+    }>;
     /**
-     * Send transaction
+     * Broadcast a pre-signed transaction (RFC-O-1 octra_submitTransaction).
+     * Use after signTransaction() to submit the signed tx to the network.
      */
-    sendTransaction(txData: TransactionData): Promise<TransactionResult>;
+    submitTransaction(signedTx: any): Promise<TransactionResult>;
     /**
      * Call a smart contract method (state-changing).
      * The extension builds, signs, and submits the transaction via octra_submit.
@@ -518,16 +520,17 @@ declare class ZeroXIOWallet extends EventEmitter {
      * Get transaction history
      */
     getTransactionHistory(page?: number, limit?: number): Promise<TransactionHistory>;
-    /**
-     * Get private balance information
-     */
     getPrivateBalanceInfo(): Promise<PrivateBalanceInfo>;
     /**
-     * Encrypt public balance to private
+     * Encrypt public balance to private.
+     * @deprecated The 0xio extension does not serve this through the bridge (it answers
+     * NOT_AVAILABLE); users encrypt from the extension's Privacy screen.
      */
     encryptBalance(amount: string | number): Promise<TransactionResult>;
     /**
-     * Decrypt private balance to public
+     * Decrypt private balance to public.
+     * @deprecated The 0xio extension does not serve this through the bridge (it answers
+     * NOT_AVAILABLE); users decrypt from the extension's Privacy screen.
      */
     decryptBalance(amount: string | number): Promise<TransactionResult>;
     /**
@@ -551,15 +554,121 @@ declare class ZeroXIOWallet extends EventEmitter {
      */
     claimPrivateTransfer(transferId: string): Promise<TransactionResult>;
     /**
-     * Sign an arbitrary message with the wallet's private key
-     * The user will be prompted to approve the signature request in the extension
+     * Send any wallet method + params through the bridge. Escape hatch for
+     * primitives that don't have a typed helper yet (no SDK upgrade needed).
+     * @since 2.8.0
+     */
+    request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Read-only node RPC through the wallet. Only the wallet's allow-listed public methods work
+     * (octra_balance, octra_transaction, contract_call and similar); writes are refused.
+     * @since 2.8.0
+     */
+    rpcCall<T = unknown>(method: string, params?: unknown[]): Promise<T>;
+    /**
+     * Feature-detect which private capabilities the connected wallet supports.
+     * Lets a dapp render the correct UI (or fail closed) before any action.
+     * @since 2.8.0
+     */
+    getPrivateCapabilities(): Promise<{
+        wallet: string;
+        version: string;
+        supports: Record<string, boolean>;
+        methods: string[];
+        required_permissions?: Record<string, string[]>;
+    }>;
+    /** Read-only contract view (no approval popup). @since 2.8.0 */
+    callContractView(params: {
+        contract: string;
+        method: string;
+        params?: unknown[];
+        caller?: string;
+    }): Promise<unknown>;
+    /** Encrypt a raw integer value to a contract-ready ciphertext (keys stay in wallet). @since 2.8.0 */
+    encryptValue(params: {
+        value_raw: string;
+        token?: string;
+        owner?: string;
+        asset?: string;
+    }): Promise<{
+        cipher: string;
+        commitment?: string;
+        encoding?: string;
+    }>;
+    /** Decrypt a ciphertext to a raw integer value. @since 2.8.0 */
+    decryptValue(params: {
+        cipher: string;
+        token?: string;
+        owner?: string;
+    }): Promise<{
+        value_raw: string;
+        display?: string;
+        decimals?: number;
+    }>;
+    /** Zero proof for a ciphertext (proves it encrypts the given value, default 0). @since 2.8.0 */
+    makeZeroProof(params: {
+        cipher: string;
+        value_raw?: string;
+        token?: string;
+        owner?: string;
+    }): Promise<{
+        proof: string;
+        commitment?: string;
+        blinding?: string;
+        encoding?: string;
+    }>;
+    /** Range proof for a ciphertext. @since 2.8.0 */
+    makeRangeProof(params: {
+        cipher: string;
+        value_raw: string;
+        token?: string;
+        owner?: string;
+        range?: {
+            min_raw: string;
+            max_raw: string;
+        };
+    }): Promise<{
+        proof: string;
+        encoding?: string;
+    }>;
+    /** Private OCT + private token balances (decrypted inside the wallet). @since 2.8.0 */
+    getPrivateBalance(params?: {
+        address?: string;
+        assets?: string[];
+        tokens?: string[];
+        include_claimable?: boolean;
+    }): Promise<unknown>;
+    /** Register a receive/view public key so an address can receive private transfers. @since 2.8.0 */
+    registerPrivateViewKey(params: {
+        address: string;
+    }): Promise<unknown>;
+    /** Submit an ordered multi-step public contract flow under one approval. @since 2.8.0 */
+    sendContractTransactionSequence(params: {
+        sequence_id?: string;
+        transactions: Array<{
+            contract: string;
+            method: string;
+            params?: unknown[];
+            amount?: string;
+            ou?: string;
+        }>;
+    }): Promise<unknown>;
+    /**
+     * Sign an arbitrary message with the wallet's private key.
+     * The user will be prompted to approve the signature request in the extension.
+     *
+     * The wallet does not sign the raw message: it signs the 0xio Signed Message framing
+     * (`"Octra Signed Message:\n" + byteLength + "\n" + message`) so a signed message can never be a
+     * transaction pre-image. Verify with `verifyMessage(message, signature, publicKey)`, or check an
+     * Ed25519 signature against `getSignedMessageBytes(message)` with your own library.
+     *
      * @param message - The message to sign (non-empty string)
      * @returns Promise resolving to the base64-encoded Ed25519 signature
      * @throws ZeroXIOWalletError with code SIGNATURE_FAILED if signing fails
      * @example
      * ```typescript
      * const signature = await wallet.signMessage('Hello, 0xio!');
-     * console.log('Signature:', signature);
+     * const ok = await verifyMessage('Hello, 0xio!', signature, await wallet.getPublicKey());
      * ```
      */
     signMessage(message: string): Promise<string>;
@@ -569,55 +678,33 @@ declare class ZeroXIOWallet extends EventEmitter {
      * to the calling service and a one-time nonce, preventing cross-service replay attacks.
      *
      * @param service - Identifies the relying service (e.g. 'MyDApp' or 'api.mydapp.com')
-     * @param nonce   - Unique one-time value — use a server-generated UUID or challenge
+     * @param nonce   - Unique one-time value. Use a server-generated UUID or challenge
      * @returns Promise resolving to the base64-encoded Ed25519 signature
      */
     signAuthMessage(service: string, nonce: string): Promise<string>;
     private ensureInitialized;
     private ensureConnected;
     private setupExtensionEventListeners;
-    /**
-     * Handle account changed event from extension
-     */
     private handleAccountChanged;
-    /**
-     * Handle network changed event from extension
-     */
     private handleNetworkChanged;
-    /**
-     * Handle balance changed event from extension
-     */
     private handleBalanceChanged;
-    /**
-     * Handle extension locked event
-     */
     private handleExtensionLocked;
-    /**
-     * Handle extension unlocked event
-     */
     private handleExtensionUnlocked;
+    private handleTransactionConfirmed;
     /**
-     * Handle transaction confirmed event
+     * The wallet takes raw micro-OCT. `amount` passes through unchanged (what every existing
+     * dapp sends today); `amountOct` is converted exactly. Never both.
      */
-    private handleTransactionConfirmed;
+    private resolveRawAmount;
     /**
-     * Clean up SDK resources
+     * Reject numeric amounts that cannot be represented exactly in micro-OCT.
+     * e.g. 0.1 + 0.2 = 0.30000000000000004: the extension would sign the wrong value.
+     * String amounts bypass this check (caller is responsible for correctness).
      */
+    private assertExactOCTAmount;
     cleanup(): void;
 }
 
-/**
- * 0xio Wallet SDK - Extension Communication Module
- *
- * @fileoverview Manages secure communication between the SDK and browser extension.
- * Implements message passing, request/response handling, rate limiting, and origin validation
- * to ensure secure wallet interactions.
- *
- * @module communication
- * @version 2.7.0
- * @license MIT
- */
-
 declare class ExtensionCommunicator extends EventEmitter {
     private pendingRequests;
     private isInitialized;
@@ -626,7 +713,7 @@ declare class ExtensionCommunicator extends EventEmitter {
     private isExtensionAvailableState;
     private trustedOrigins;
     private _parentOrigin;
-    /** Pluggable transport — defaults to the 0xio postMessage protocol. */
+    /** Pluggable transport, defaults to the 0xio postMessage protocol. */
     private adapter;
     /** Teardown fn returned by adapter.listen() */
     private _adapterTeardown;
@@ -634,14 +721,14 @@ declare class ExtensionCommunicator extends EventEmitter {
     private _adapterReadyTeardown;
     /**
      * Set when a trusted walletReady has been received from window.parent.
-     * The polling fallback must NOT clear this flag.
+     * The polling fallback must not clear this flag.
      */
     private _parentTrusted;
     /** walletReady postMessage listener stored for cleanup */
     private _walletReadyMessageListener;
     /**
      * In-flight interactive request lock.
-     * Methods that open approval popups are serialized — only one at a time.
+     * Methods that open approval popups are serialized: only one at a time.
      */
     private _interactiveInFlight;
     private readonly MAX_CONCURRENT_REQUESTS;
@@ -653,6 +740,8 @@ declare class ExtensionCommunicator extends EventEmitter {
     initialize(): Promise<boolean>;
     isExtensionAvailable(): boolean;
     private static readonly NO_RETRY_METHODS;
+    private static readonly LONG_COMPUTE_METHODS;
+    private static readonly PROOF_METHODS;
     private static readonly INTERACTIVE_METHODS;
     sendRequest<T = any>(method: string, params?: any, timeout?: number): Promise<T>;
     sendRequestWithRetry<T = any>(method: string, params?: any, maxRetries?: number, timeout?: number): Promise<T>;
@@ -672,7 +761,7 @@ declare class ExtensionCommunicator extends EventEmitter {
     private getExtensionDiagnostics;
     /**
      * Clean up SDK resources.
-     * After cleanup() the instance is terminal — do not call initialize() again.
+     * After cleanup() the instance is terminal: do not call initialize() again.
      * Construct a new instance instead.
      */
     cleanup(): void;
@@ -697,7 +786,7 @@ declare class ExtensionCommunicator extends EventEmitter {
  *   window.postMessage({ source: '0xio-sdk-bridge', response: { id, success, data, error }, sessionNonce })
  *   window.postMessage({ source: '0xio-sdk-bridge', event: { type, data } })
  *
- * H-2: Session nonce validation — injected.ts broadcasts the nonce received from the
+ * Session nonce validation: injected.ts broadcasts the nonce received from the
  * isolated content script. Once set, any '0xio-sdk-bridge' response with a missing or
  * mismatched nonce is rejected, preventing response injection by malicious page scripts.
  */
@@ -715,7 +804,7 @@ declare const ZeroXIOAdapter: WalletTransportAdapter;
  *
  * Targets any wallet that exposes `window.octra` per the RFC-O-1 specification:
  *   window.octra.isOctra === true
- *   window.octra.request({ method, params }) → Promise<unknown>
+ *   window.octra.request({ method, params }) returns Promise<unknown>
  *   window.octra.on(event, listener) / removeListener(event, listener)
  *
  * This adapter translates the SDK's internal method names into RFC-O-1 method
@@ -730,7 +819,7 @@ declare function createOctraProviderAdapter(): WalletTransportAdapter;
 declare const OctraProviderAdapter: WalletTransportAdapter;
 
 /**
- * 0xio SDK — Wallet Adapter Registry
+ * 0xio SDK: Wallet Adapter Registry
  *
  * Add new wallet adapters here. Detection order determines which wallet takes
  * priority when multiple wallets are installed at the same time.
@@ -749,6 +838,19 @@ declare function detectWalletAdapter(): WalletTransportAdapter | null;
 /** Returns all registered adapter instances. */
 declare function getAllAdapters(): WalletTransportAdapter[];
 
+/** Scope names the 0xio wallet enforces. Any other name is dropped at connect. */
+declare const WALLET_PERMISSIONS: readonly ["accounts", "public_transactions", "contract_calls", "contract_views", "private_balance_read", "private_proofs", "private_transfers", "private_claims"];
+type WalletPermission = (typeof WALLET_PERMISSIONS)[number];
+/** Older SDK permission names and the wallet scope each one means. */
+declare const LEGACY_PERMISSION_MAP: Record<string, WalletPermission>;
+/** Translate any mix of old and new names into the wallet's scope names, without duplicates. */
+declare function toWalletPermissions(perms: readonly string[] | undefined): WalletPermission[];
+/**
+ * The granted wallet scopes plus every requested old name they satisfy, so a dapp that checks
+ * for the name it asked for (for example 'read_balance') keeps seeing it.
+ */
+declare function withLegacyAliases(granted: readonly string[] | undefined, requested: readonly string[] | undefined): Permission[];
+
 /**
  * Network configuration for 0xio SDK
  */
@@ -761,12 +863,12 @@ declare const NETWORKS: Readonly<Record<string, Readonly<NetworkInfo>>>;
 declare const DEFAULT_NETWORK_ID = "mainnet";
 /**
  * Get network configuration by ID.
- * Returns a frozen copy — callers cannot mutate SDK-internal state.
+ * Returns a frozen copy, so callers cannot mutate SDK-internal state.
  */
 declare function getNetworkConfig(networkId?: string): NetworkInfo;
 /**
  * Get all available networks.
- * Returns frozen copies — callers cannot mutate SDK-internal state.
+ * Returns frozen copies, so callers cannot mutate SDK-internal state.
  */
 declare function getAllNetworks(): NetworkInfo[];
 /**
@@ -776,32 +878,18 @@ declare function isValidNetworkId(networkId: string): boolean;
 
 /**
  * Default balance structure.
- * Accepts a numeric total or undefined — never pass a Balance object here.
+ * Accepts a numeric total or undefined. Never pass a Balance object here.
  */
 declare function createDefaultBalance(total?: number): Balance;
-/**
- * SDK Configuration constants
- */
 declare const SDK_CONFIG: {
-    readonly version: "2.7.0";
+    readonly version: "2.8.0";
     readonly defaultNetworkId: "mainnet";
     readonly communicationTimeout: 30000;
     readonly retryAttempts: 3;
     readonly retryDelay: 1000;
 };
-/**
- * Get default network configuration
- */
 declare function getDefaultNetwork(): NetworkInfo;
 
-/**
- * 0xio Wallet SDK - Utilities
- * Helper functions for validation, formatting, and common operations
- */
-
-/**
- * Validate wallet address for Octra blockchain
- */
 declare function isValidAddress(address: string): boolean;
 /**
  * Validate transaction amount.
@@ -809,70 +897,33 @@ declare function isValidAddress(address: string): boolean;
  * String amounts avoid JS number precision loss for very large values.
  */
 declare function isValidAmount(amount: string | number): boolean;
-/**
- * Validate transaction message
- */
 declare function isValidMessage(message: string): boolean;
-/**
- * Validate fee level
- */
 declare function isValidFeeLevel(feeLevel: number): boolean;
 /**
  * Derive the canonical Octra address from a base64-encoded Ed25519 public key.
- * Algorithm: SHA-256(pubkey_bytes) → base58 → prepend "oct"
+ * Algorithm: SHA-256 of the pubkey bytes, base58-encoded, with "oct" prepended
  * Source of truth: ocho-push-server/src/index.ts#deriveAddressFromPubkey
  */
 declare function deriveOctraAddress(publicKeyBase64: string): Promise<string>;
-/**
- * Format OCT amount for display
- */
 declare function formatOCT(amount: number | string, decimals?: number): string;
-/**
- * Format address for display (truncated)
- */
 declare function formatAddress(address: string, prefixLength?: number, suffixLength?: number): string;
-/**
- * Format timestamp for display
- */
 declare function formatTimestamp(timestamp: number): string;
-/**
- * Format transaction hash for display
- */
 declare function formatTxHash(hash: string, length?: number): string;
-/**
- * Convert OCT to micro OCT (for network transmission)
- */
 declare function toMicroOCT(amount: number): string;
 /**
- * Convert micro OCT to OCT (for display)
+ * Exact OCT to raw micro-OCT conversion using string arithmetic (no float rounding).
+ * Accepts up to 6 decimals; anything else is rejected.
  */
+declare function octToMicro(amount: string | number): string;
 declare function fromMicroOCT(microAmount: string | number): number;
-/**
- * Create standardized error messages
- */
 declare function createErrorMessage(code: ErrorCode, context?: string): string;
-/**
- * Check if error is a specific type
- */
 declare function isErrorType(error: any, code: ErrorCode): boolean;
-/**
- * Create a promise that resolves after a delay
- */
 declare function delay(ms: number): Promise<void>;
-/**
- * Check if running in browser environment
- */
 declare function isBrowser(): boolean;
-/**
- * Check if browser supports required features
- */
 declare function checkBrowserSupport(): {
     supported: boolean;
     missingFeatures: string[];
 };
-/**
- * Generate mock data for development/testing
- */
 declare function generateMockData(): {
     address: string;
     balance: {
@@ -893,9 +944,6 @@ declare function generateMockData(): {
         isTestnet: boolean;
     };
 };
-/**
- * Create development logger
- */
 declare function createLogger(prefix: string, debug: boolean): {
     log: (...args: any[]) => void;
     warn: (...args: any[]) => void;
@@ -906,7 +954,50 @@ declare function createLogger(prefix: string, debug: boolean): {
     groupEnd: () => void;
 };
 
-declare const SDK_VERSION = "2.7.0";
+/**
+ * 0xio Signed Message standard (v1).
+ *
+ * `wallet.signMessage(message)` never signs the raw message. The wallet frames it first so a signed
+ * "message" can never collide with a transaction pre-image (a transaction is canonical JSON that
+ * begins with '{'). The framing is:
+ *
+ *     "Octra Signed Message:\n" + utf8ByteLength(message) + "\n" + message
+ *
+ * signed as an Ed25519 detached signature over the UTF-8 bytes of that string. The leading 'O'
+ * guarantees the signed bytes never begin with '{', so a personal-message signature can never be a
+ * valid transaction. Any verifier MUST reconstruct the same bytes: use `getSignedMessageBytes()`
+ * with any Ed25519 library, or `verifyMessage()` for a batteries-included check.
+ */
+/** Fixed prefix tag for the 0xio Signed Message scheme. */
+declare const SIGNED_MESSAGE_PREFIX = "Octra Signed Message:";
+/** Scheme version, bumped if the framing ever changes so verifiers can detect it. */
+declare const SIGNED_MESSAGE_VERSION = 1;
+/**
+ * The exact bytes that `wallet.signMessage(message)` produces a signature over. Verify a 0xio
+ * message signature by checking an Ed25519 signature against these bytes with the signer's public
+ * key. Zero-dependency - bring your own Ed25519 verifier, or use `verifyMessage`.
+ */
+declare function getSignedMessageBytes(message: string): Uint8Array;
+/**
+ * Reconstruct the auth message that `wallet.signAuthMessage(service, nonce)` signs. A relying
+ * service verifies an auth signature with `verifyMessage(buildAuthMessage(service, nonce, origin),
+ * signature, publicKey)`, where `origin` is the caller's page origin.
+ */
+declare function buildAuthMessage(service: string, nonce: string, origin: string): string;
+/**
+ * Verify a 0xio message signature produced by `wallet.signMessage`.
+ *
+ * @param message   The original message passed to `wallet.signMessage`.
+ * @param signature Base64 Ed25519 signature returned by `wallet.signMessage`.
+ * @param publicKey Base64 Ed25519 public key of the signer (from `wallet.getPublicKey()`).
+ * @returns         Whether the signature is valid for this message and key.
+ *
+ * Uses the Web Crypto Ed25519 primitive (Node 18+, Chrome 137+, Safari 17+, Firefox 129+). In an
+ * environment without it, verify `getSignedMessageBytes(message)` with your own Ed25519 library.
+ */
+declare function verifyMessage(message: string, signature: string, publicKey: string): Promise<boolean>;
+
+declare const SDK_VERSION = "2.8.0";
 declare const MIN_EXTENSION_VERSION = "2.0.1";
 declare const MIN_EXTENSION_VERSION_DEVNET = "2.2.1";
 declare const SUPPORTED_EXTENSION_VERSIONS = "^2.0.1";
@@ -923,5 +1014,5 @@ declare function checkSDKCompatibility(): {
     recommendations: string[];
 };
 
-export { DEFAULT_NETWORK_ID, ErrorCode, EventEmitter, ExtensionCommunicator, MIN_EXTENSION_VERSION, MIN_EXTENSION_VERSION_DEVNET, NETWORKS, OctraProviderAdapter, SDK_CONFIG, SDK_VERSION, SUPPORTED_EXTENSION_VERSIONS, ZeroXIOAdapter, ZeroXIOWallet, ZeroXIOWalletError, checkBrowserSupport, checkSDKCompatibility, createDefaultBalance, createErrorMessage, createLogger, createOctraProviderAdapter, createZeroXIOAdapter, createZeroXIOWallet, delay, deriveOctraAddress, detectWalletAdapter, formatAddress, formatOCT, formatTimestamp, formatTxHash, formatOCT as formatZeroXIO, fromMicroOCT, fromMicroOCT as fromMicroZeroXIO, generateMockData, getAllAdapters, getAllNetworks, getDefaultNetwork, getNetworkConfig, isBrowser, isErrorType, isValidAddress, isValidAmount, isValidFeeLevel, isValidMessage, isValidNetworkId, toMicroOCT, toMicroOCT as toMicroZeroXIO };
-export type { AccountChangedEvent, AdapterIncomingMessage, AdapterRequest, Balance, BalanceChangedEvent, ConnectEvent, ConnectOptions, ConnectionInfo, ContractCallData, ContractParam, ContractParams, ContractViewCallData, DisconnectEvent, ErrorEvent, ExtensionRequest, ExtensionResponse, NetworkChangedEvent, NetworkInfo, PendingPrivateTransfer, Permission, PrivateBalanceInfo, PrivateTransferData, SDKConfig, SignedTransaction, Transaction, TransactionConfirmedEvent, TransactionData, TransactionFinality, TransactionHistory, TransactionResult, WalletAddress, WalletEvent, WalletEventType, WalletTransportAdapter };
+export { DEFAULT_NETWORK_ID, ErrorCode, EventEmitter, ExtensionCommunicator, LEGACY_PERMISSION_MAP, MIN_EXTENSION_VERSION, MIN_EXTENSION_VERSION_DEVNET, NETWORKS, OctraProviderAdapter, SDK_CONFIG, SDK_VERSION, SIGNED_MESSAGE_PREFIX, SIGNED_MESSAGE_VERSION, SUPPORTED_EXTENSION_VERSIONS, WALLET_PERMISSIONS, ZeroXIOAdapter, ZeroXIOWallet, ZeroXIOWalletError, buildAuthMessage, checkBrowserSupport, checkSDKCompatibility, createDefaultBalance, createErrorMessage, createLogger, createOctraProviderAdapter, createZeroXIOAdapter, createZeroXIOWallet, delay, deriveOctraAddress, detectWalletAdapter, formatAddress, formatOCT, formatTimestamp, formatTxHash, formatOCT as formatZeroXIO, fromMicroOCT, fromMicroOCT as fromMicroZeroXIO, generateMockData, getAllAdapters, getAllNetworks, getDefaultNetwork, getNetworkConfig, getSignedMessageBytes, isBrowser, isErrorType, isValidAddress, isValidAmount, isValidFeeLevel, isValidMessage, isValidNetworkId, octToMicro, toMicroOCT, toMicroOCT as toMicroZeroXIO, toWalletPermissions, verifyMessage, withLegacyAliases };
+export type { AccountChangedEvent, AdapterIncomingMessage, AdapterRequest, Balance, BalanceChangedEvent, ConnectEvent, ConnectOptions, ConnectionInfo, ContractCallData, ContractParam, ContractParams, ContractViewCallData, DisconnectEvent, ErrorEvent, ExtensionRequest, ExtensionResponse, NetworkChangedEvent, NetworkInfo, PendingPrivateTransfer, Permission, PrivateBalanceInfo, PrivateTransferData, SDKConfig, SignedTransaction, Transaction, TransactionConfirmedEvent, TransactionData, TransactionFinality, TransactionHistory, TransactionResult, WalletAddress, WalletEvent, WalletEventType, WalletPermission, WalletTransportAdapter };