SDK Integration Guide

npm install vite-plugin-node-polyfills

import { defineConfig } from 'vite';
import { nodePolyfills } from 'vite-plugin-node-polyfills';

export default defineConfig({
  plugins: [
    nodePolyfills({
      include: ['buffer', 'process', 'util', 'stream', 'events'],
      globals: {
        Buffer: true,
        global: true,
        process: true,
      },
    }),
  ],
});

// webpack.config.js
const webpack = require('webpack');

module.exports = {
  // ...
  resolve: {
    fallback: {
      "crypto": require.resolve("crypto-browserify"),
      "stream": require.resolve("stream-browserify"),
      "buffer": require.resolve("buffer/"),
      "process": require.resolve("process/browser"),
    }
  },
  plugins: [
    new webpack.ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
      process: 'process/browser',
    }),
  ]
};

import { createZeroXIOWallet } from '@0xio/sdk';

// One-liner: create, initialize, and auto-connect
const wallet = await createZeroXIOWallet({
  appName: 'My Privacy dApp',
  appDescription: 'An encrypted DeFi protocol on Octra',
  autoConnect: true,  // Auto-reconnects if user previously approved
});

const balance = await wallet.getBalance(true);
console.log('Public:', balance.public, 'OCT');
console.log('Private:', balance.private, 'OCT');

import { ZeroXIOWallet } from '@0xio/sdk';

const wallet = new ZeroXIOWallet({
  appName: 'My Privacy dApp',
  appDescription: 'An encrypted DeFi protocol on Octra',
});

// Initialize: detects 0xio extension or any RFC-O-1 wallet
const isAvailable = await wallet.initialize();
if (!isAvailable) {
  console.log("No compatible wallet detected.");
  return;
}

// Connect: the user approves in the wallet popup
const result = await wallet.connect({
  permissions: ['accounts', 'public_transactions']
});
console.log('Connected to:', result.address);
console.log('Network:', result.networkInfo.name);

await wallet.sendTransaction({ to, amountOct: '10.5' });   // 10.5 OCT
await wallet.sendTransaction({ to, amount: '10500000' });  // the same, in raw units

const wallet = new ZeroXIOWallet({
  appName: 'My DApp',
  trustedParentOrigins: ['https://desktop.0xio.xyz'],
});

import { ZeroXIOWallet } from '@0xio/sdk';

const wallet = new ZeroXIOWallet({ appName: 'My DApp' });
await wallet.initialize(); // Finds window.octra from any compliant wallet
await wallet.connect();    // Uses RFC-O-1 request() under the hood

import { OctraProviderAdapter } from '@0xio/sdk';

// Check if any RFC-O-1 wallet is available
if (OctraProviderAdapter.detect()) {
  const accounts = await window.octra.request({ method: 'octra_requestAccounts' });
  const balance = await window.octra.request({ method: 'octra_getEncryptedBalance' });
}

const success = await wallet.initialize();
if (success) {
  console.log('SDK ready!');
}

if (wallet.isReady()) {
  // Safe to make requests
}

const result = await wallet.connect({
  permissions: [
    'accounts',             // address, balance, public key
    'public_transactions',  // sends and message signing
    'private_balance_read'  // private balance (optional, shows a warning)
  ]
});

console.log('Connected:', result.address);
console.log('Balance:', result.balance.total, 'OCT');
console.log('Network:', result.networkInfo.name);

await wallet.disconnect();

const connected = wallet.isConnected();

const info = wallet.getConnectionInfo();
console.log(info.address);
console.log(info.balance);
console.log(info.connectedAt);

const status = await wallet.getConnectionStatus();
if (status.isConnected) {
  console.log('Already connected to:', status.address);
}

const address = wallet.getAddress();
// Returns: "oct1abc123..." or null if not connected

const publicKey = await wallet.getPublicKey();

// Detect wrong network
const networkId = wallet.getNetworkId(); // 'mainnet' or 'devnet'
if (networkId !== 'devnet') {
  try {
    const result = await wallet.switchNetwork('devnet');
    console.log('Switched:', result.switched); // true once the user confirmed
  } catch (e) {
    // USER_REJECTED: the user kept the current network
  }
}

const networkId = wallet.getNetworkId();
// Returns: 'mainnet', 'devnet', or null

const balance = await wallet.getBalance(true); // Force refresh

console.log(balance.public);  // 1250.5 (number)
console.log(balance.private); // 3420.25 (number)
console.log(balance.total);   // 4670.75 (number)
console.log(balance.currency); // "OCT"

interface Balance {
  public: number;    // Public balance in OCT
  private: number;   // Private (FHE) balance in OCT
  total: number;     // Combined balance
  currency: 'OCT';   // Currency symbol
}

const result = await wallet.sendTransaction({
  to: 'oct1qv...',
  amountOct: '10.5',              // 10.5 OCT, converted exactly by the SDK
  message: 'Payment for services' // Optional
});

console.log('Transaction Hash:', result.hash);
console.log('Accepted:', result.accepted);

const { signedTx } = await wallet.signTransaction({ to: 'oct1qv...', amountOct: '1' });
const result = await wallet.submitTransaction(signedTx);

const result = await wallet.sendPrivateTransfer({
  to: 'oct1x...',
  amount: 20  // OCT
});
console.log('TX Hash:', result.hash);

const history = await wallet.getTransactionHistory(1, 20);

history.transactions.forEach(tx => {
  console.log(`${tx.from} to ${tx.to}: ${Number(tx.amount) / 1_000_000} OCT`); // rows carry raw micro-OCT
});

console.log('Total:', history.totalCount);
console.log('Has more:', history.hasMore);

// Simple message signing
const signature = await wallet.signMessage('Hello, 0xio!');
console.log('Signature:', signature);

// Authentication challenge with timestamp
const timestamp = Date.now();
const challenge = `Sign in to MyDApp\nTimestamp: ${timestamp}\nAddress: ${wallet.getAddress()}`;
const authSignature = await wallet.signMessage(challenge);

// API key creation (for 0xio Oracle/Indexer)
const owner = wallet.getAddress();
const ts = Math.floor(Date.now() / 1000);
const apiKeyMessage = `0xio-api-key:${owner}:${ts}`;
const signature = await wallet.signMessage(apiKeyMessage);

const signature = await wallet.signAuthMessage('MyDApp', 'abc123');
// Signs: "0xio auth\nService: MyDApp\nNonce: abc123\nOrigin: https://mydapp.com"

import { verifyMessage } from '@0xio/sdk';

const publicKey = await wallet.getPublicKey(); // base64
const valid = await verifyMessage('Hello, 0xio!', signature, publicKey);

import { getSignedMessageBytes } from '@0xio/sdk';
import nacl from 'tweetnacl';

const ok = nacl.sign.detached.verify(
  getSignedMessageBytes(message),
  base64ToBytes(signature),
  base64ToBytes(publicKey),
);

import { ContractCallData } from '@0xio/sdk';

const result = await wallet.callContract({
  contract: 'oct26LiaGUz78Jnby2TWEHcmboKHyupnu1NX1G3Evz28YHm',
  method: 'swap',
  params: [100000, true, 90000],  // Flat primitives, not array-wrapped
  amountOct: '0',  // Value to attach in OCT (optional, default none); or amount in raw micro-OCT
  ou: '10000',     // Operational units (optional, default '10000')
});

console.log('TX Hash:', result.txHash);
console.log('Success:', result.success);

// Query contract state
const price = await wallet.contractCallView({
  contract: 'oct26LiaGUz78Jnby2TWEHcmboKHyupnu1NX1G3Evz28YHm',
  method: 'get_active_price',
  params: [],
});
console.log('Active price:', price);

// Query with parameters
const reserves = await wallet.contractCallView({
  contract: 'oct26LiaGUz78Jnby2TWEHcmboKHyupnu1NX1G3Evz28YHm',
  method: 'get_bin_reserves',
  params: [8388608],
  caller: 'oct1youraddress...',  // Optional caller context
});
console.log('Reserves:', reserves);

const totalSupply = await wallet.getContractStorage(
  'oct7qrpW3T8mXYbZfAZrkLQKGAtD6ZswCf9Px5jPXnfmtiK',
  'total_supply'
);
console.log('Total supply:', totalSupply);

// Returns null if key doesn't exist
const missing = await wallet.getContractStorage(contractAddr, 'nonexistent');
console.log(missing); // null

const result = await wallet.sendContractTransactionSequence({
  transactions: [
    { contract: 'oct26Lia...', method: 'approve', params: [poolAddress, 1000000] },
    { contract: 'oct26Lia...', method: 'swap', params: [1000000, true, 900000] },
  ],
});

const account = await wallet.rpcCall('octra_balance', [wallet.getAddress()]);

const result = await wallet.encryptBalance(5.0);
console.log('TX Hash:', result.txHash);
console.log('Success:', result.success);

const result = await wallet.decryptBalance(10.0);
console.log('TX Hash:', result.txHash);
console.log('Success:', result.success);

const info = await wallet.getPrivateBalanceInfo();
console.log('Has private balance:', info.hasPrivateBalance);
console.log('Can decrypt:', info.canDecrypt);

const pending = await wallet.getPendingPrivateTransfers();

pending.forEach(transfer => {
  console.log(`Output ${transfer.id}: ${Number(transfer.amount) / 1_000_000} OCT`);
});

const result = await wallet.claimPrivateTransfer('transfer_123');
console.log('Claimed! TX:', result.hash);

const caps = await wallet.getPrivateCapabilities();
if (caps.supports.encrypt_value) {
  const { cipher } = await wallet.encryptValue({ value_raw: '1000000' }); // 1 OCT
  const { proof, commitment, blinding } = await wallet.makeZeroProof({ cipher, value_raw: '1000000' });
}

const network = await wallet.getNetworkInfo();
console.log('Network:', network.name);
console.log('RPC:', network.rpcUrl);
console.log('Explorer:', network.explorerUrl);
console.log('Is Testnet:', network.isTestnet);

wallet.on('accountChanged', (event) => {
  console.log('New Address:', event.data.newAddress);
  console.log('Previous Address:', event.previousAddress);
  console.log('Balance:', event.data.balance);

  // Re-fetch user data, update UI
  updateUserInterface(event.data.newAddress);
});

wallet.on('networkChanged', (event) => {
  console.log('Previous:', event.previousNetwork?.name);
  console.log('New:', event.data.newNetwork.name);

  // Update RPC endpoint, refresh data
  reconnectToNetwork(event.data.newNetwork);
});

wallet.on('balanceChanged', (event) => {
  console.log('Address:', event.data.address);
  console.log('Previous:', event.data.previousBalance?.total);
  console.log('New:', event.data.newBalance.total);

  // Update UI with new amounts
  updateBalanceDisplay(event.data.newBalance);
});

wallet.on('connect', (event) => {
  console.log('Connected to:', event.data.address);
  console.log('Balance:', event.data.balance.total);
  console.log('Permissions:', event.data.permissions);
});

wallet.on('disconnect', (event) => {
  console.log('Disconnect Reason:', event.reason);
  // Possible reasons: 'user_action', 'extension_locked', 'network_error'

  // Clear user session, show connect button
  clearUserSession();
  showConnectModal();
});

wallet.on('transactionConfirmed', (event) => {
  console.log('TX Hash:', event.txHash);
  console.log('Confirmations:', event.confirmations);
});

wallet.on('transactionFailed', (event) => {
  console.log('TX ID:', event.data.txId, 'reason:', event.data.error);
});

wallet.on('extensionLocked', () => {
  console.log('Wallet locked - user needs to unlock');
});

wallet.on('extensionUnlocked', () => {
  console.log('Wallet unlocked');
});

// Remove specific listener
wallet.off('accountChanged', handlerFunction);

// Remove all listeners for an event
wallet.removeAllListeners('balanceChanged');

// Remove all listeners
wallet.removeAllListeners();

wallet.cleanup();

import {
  ZeroXIOWalletError,
  ErrorCode
} from '@0xio/sdk';

try {
  await wallet.sendTransaction({
    to: 'oct1...',
    amountOct: '100'
  });
} catch (error) {
  if (error instanceof ZeroXIOWalletError) {
    switch (error.code) {
      case ErrorCode.NOT_CONNECTED:
        console.log('Connect first');
        break;

      case ErrorCode.USER_REJECTED:
        console.log('User cancelled the transaction');
        showNotification('Transaction cancelled');
        break;

      case ErrorCode.INSUFFICIENT_BALANCE:
        console.log('Not enough balance');
        showNotification('Insufficient funds');
        break;

      case ErrorCode.EXTENSION_NOT_FOUND:
        console.log('0xio Extension not installed');
        showInstallPrompt();
        break;

      case ErrorCode.NETWORK_ERROR:
        console.log('Network connection issue');
        showRetryOption();
        break;

      case ErrorCode.INVALID_ADDRESS:
        console.log('Invalid recipient address');
        showError('Please check the address');
        break;

      case ErrorCode.WALLET_LOCKED:
        console.log('Wallet is locked');
        showError('Please unlock your wallet');
        break;

      case ErrorCode.PERMISSION_DENIED:
        console.log('Permission not granted');
        break;

      case ErrorCode.TRANSACTION_FAILED:
        console.log('Transaction failed:', error.message);
        break;

      case ErrorCode.SIGNATURE_FAILED:
        console.log('Signing failed:', error.message);
        showError('Failed to sign message');
        break;

      default:
        console.error('Unexpected error:', error.message);
    }

    // Access error details
    if (error.details) {
      console.log('Details:', error.details);
    }
  } else {
    console.error('Unknown error:', error);
  }
}

import { useEffect, useState, useCallback } from 'react';
import { ZeroXIOWallet, Balance, ConnectEvent } from '@0xio/sdk';

// Singleton instance to prevent multiple listeners
let walletInstance: ZeroXIOWallet | null = null;

export function useWallet() {
  const [wallet, setWallet] = useState<ZeroXIOWallet | null>(walletInstance);
  const [address, setAddress] = useState<string | null>(null);
  const [balance, setBalance] = useState<Balance | null>(null);
  const [isConnected, setIsConnected] = useState(false);
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    let mounted = true;

    async function init() {
      // Return existing instance if ready
      if (walletInstance) {
        if (mounted) {
          setWallet(walletInstance);
          setIsReady(true);
          walletInstance.getConnectionStatus().then(status => {
             if (status.isConnected && mounted) {
                setAddress(status.address || null);
                setIsConnected(true);
             }
          });
        }
        return;
      }

      // Create new instance
      const sdk = new ZeroXIOWallet({ 
        appName: 'My DApp',
        debug: true 
      });

      try {
        // Initialize (waits for extension)
        const ready = await sdk.initialize();
        if (ready && mounted) {
           walletInstance = sdk;
           setWallet(sdk);
           setIsReady(true);
           
           // Check existing connection
           const status = await sdk.getConnectionStatus();
           if (status.isConnected) {
             setAddress(status.address || null);
             setIsConnected(true);
           }
        }
      } catch (e) {
        console.error("SDK Init failed:", e);
      }
    }

    init();

    // Setup listeners if wallet exists
    if (wallet) {
      const handleConnect = (event: ConnectEvent) => {
        if (!mounted) return;
        setAddress(event.data.address);
        setBalance(event.data.balance);
        setIsConnected(true);
      };

      const handleDisconnect = () => {
        if (!mounted) return;
        setAddress(null);
        setBalance(null);
        setIsConnected(false);
      };

      const handleAccountChanged = (event: any) => {
        if (!mounted) return;
        setAddress(event.data.newAddress);
        if (event.data.balance) setBalance(event.data.balance);
      };

      wallet.on('connect', handleConnect);
      wallet.on('disconnect', handleDisconnect);
      wallet.on('accountChanged', handleAccountChanged);

      return () => {
        wallet.off('connect', handleConnect);
        wallet.off('disconnect', handleDisconnect);
        wallet.off('accountChanged', handleAccountChanged);
      };
    }
  }, [wallet]);

  const connect = useCallback(async () => {
    if (!wallet) throw new Error("Wallet SDK not initialized");
    try {
      const result = await wallet.connect({
        permissions: ['accounts', 'public_transactions']
      });
      setAddress(result.address);
      setBalance(result.balance);
      setIsConnected(true);
    } catch (error) {
      console.error('Connection failed:', error);
      throw error;
    }
  }, [wallet]);

  // ... other methods (disconnect, signMessage, etc)

  return {
    wallet,
    address,
    balance,
    isConnected,
    isReady,
    connect
  };
}

import { ref, onMounted, onUnmounted } from 'vue';
import { ZeroXIOWallet, Balance } from '@0xio/sdk';

export function useWallet() {
  const wallet = new ZeroXIOWallet({ appName: 'My DApp' });
  const address = ref<string | null>(null);
  const balance = ref<Balance | null>(null);
  const isConnected = ref(false);
  const isReady = ref(false);

  onMounted(async () => {
    await wallet.initialize();
    isReady.value = true;

    // Check for existing connection
    wallet.getConnectionStatus();

    wallet.on('connect', (event) => {
      address.value = event.data.address;
      balance.value = event.data.balance;
      isConnected.value = true;
    });

    wallet.on('disconnect', () => {
      address.value = null;
      balance.value = null;
      isConnected.value = false;
    });

    wallet.on('balanceChanged', (event) => {
      balance.value = event.data.newBalance;
    });
  });

  onUnmounted(() => {
    wallet.removeAllListeners();
  });

  const connect = async () => {
    try {
      const result = await wallet.connect({
        permissions: ['accounts', 'public_transactions']
      });
      address.value = result.address;
      balance.value = result.balance;
      isConnected.value = true;
    } catch (error) {
      console.error('Connection failed:', error);
      throw error;
    }
  };

  const disconnect = async () => {
    await wallet.disconnect();
  };

  const signMessage = async (message: string) => {
    if (!isConnected.value) throw new Error('Not connected');
    return await wallet.signMessage(message);
  };

  return { wallet, address, balance, isConnected, isReady, connect, disconnect, signMessage };
}

import type {
  // Core types
  WalletAddress,
  Balance,
  NetworkInfo,
  ConnectionInfo,
  ConnectOptions,
  SDKConfig,

  // Transaction types
  TransactionData,
  SignedTransaction,
  TransactionResult,
  TransactionFinality, // 'pending' | 'confirmed' | 'rejected' | 'dropped'
  TransactionHistory,
  Transaction,

  // Event types
  WalletEventType,
  WalletEvent,
  ConnectEvent,
  DisconnectEvent,
  AccountChangedEvent,
  BalanceChangedEvent,
  NetworkChangedEvent,
  TransactionConfirmedEvent,
  ErrorEvent,

  // Contract types
  ContractCallData,
  ContractViewCallData,
  ContractParams,

  // Private balance types
  PrivateBalanceInfo,
  PrivateTransferData,
  PendingPrivateTransfer,

  // Permission types
  Permission
} from '@0xio/sdk';

// Key type definitions
interface Balance {
  public: number;     // Public balance in OCT
  private: number;    // Private (FHE) balance in OCT
  total: number;      // Combined balance
  currency: 'OCT';    // Currency symbol
}

interface TransactionData {
  to: string;                   // Recipient address
  amount?: string | number;     // Raw micro-OCT, sent to the wallet as is
  amountOct?: string | number;  // Amount in OCT, converted by the SDK. One of the two.
  message?: string;             // Optional memo
  feeLevel?: 1 | 3;             // 1 = standard, 3 = priority
  isPrivate?: boolean;          // Use private transfer
}

interface NetworkInfo {
  id: string;                    // 'mainnet' | 'devnet' | 'custom'
  name: string;                  // Display name
  rpcUrl: string;                // RPC endpoint
  explorerUrl?: string;          // Transaction explorer base URL
  explorerAddressUrl?: string;   // Address explorer base URL
  indexerUrl?: string;           // Indexer/API base URL
  supportsPrivacy: boolean;      // FHE encrypted balance support
  color: string;                 // Brand color hex
  isTestnet: boolean;            // Whether this is a test network
}

// Contract parameter types
type ContractParams = ReadonlyArray<string | number | boolean>;

type Permission =
  // Wallet scope names
  | 'accounts' | 'public_transactions' | 'contract_calls' | 'contract_views'
  | 'private_balance_read' | 'private_proofs' | 'private_transfers' | 'private_claims'
  // Older names, translated at connect
  | 'read_address' | 'read_balance' | 'read_public_key' | 'send_transactions' | 'sign_messages'
  | 'view_private_balance' | 'view_encrypted_balance' | 'encrypt_balance' | 'decrypt_balance'
  | 'stealth_scan' | 'stealth_claim';

import {
  // Validation
  isValidAddress,
  isValidAmount,
  isValidMessage,
  isValidFeeLevel,
  isValidNetworkId,

  // Formatting
  formatOCT,
  formatAddress,
  formatTimestamp,
  formatTxHash,

  // Conversion
  toMicroOCT,
  fromMicroOCT,
  octToMicro,        // exact string conversion, at most 6 decimals

  // Permissions
  toWalletPermissions,
  withLegacyAliases,

  // Address derivation
  deriveOctraAddress, // async: base64 Ed25519 pubkey to an "oct..." address

  // Error utilities
  createErrorMessage,
  isErrorType,

  // Async utilities
  delay,
  retry,
  withTimeout,

  // Browser utilities
  isBrowser,
  checkBrowserSupport,

  // Development utilities
  generateMockData,
  createLogger
} from '@0xio/sdk';

// Examples
if (isValidAddress('oct1...')) {
  console.log('Valid address');
}

const formatted = formatOCT(123.456789, 2); // "123.46"
const shortAddr = formatAddress('oct1abc...xyz'); // "oct1ab...xyz"

const micro = toMicroOCT(1.5); // "1500000"
const exact = octToMicro('10.5'); // "10500000"
const oct = fromMicroOCT(1500000); // 1.5

// Derive an Octra address from a base64 Ed25519 public key
const addr = await deriveOctraAddress(publicKeyBase64); // "oct..."

await delay(1000); // Wait 1 second

import {
  SDK_VERSION,
  MIN_EXTENSION_VERSION,
  MIN_EXTENSION_VERSION_DEVNET,
  SUPPORTED_EXTENSION_VERSIONS,
  checkSDKCompatibility
} from '@0xio/sdk';

console.log('SDK Version:', SDK_VERSION); // "2.8.1"
console.log('Min Extension (Mainnet):', MIN_EXTENSION_VERSION); // "2.0.1"
console.log('Min Extension (Devnet):', MIN_EXTENSION_VERSION_DEVNET); // "2.2.1"
console.log('Supported:', SUPPORTED_EXTENSION_VERSIONS); // "^2.0.1"

// Check browser compatibility
const { compatible, issues, recommendations } = checkSDKCompatibility();
if (!compatible) {
  console.log('Issues:', issues);
  console.log('Recommendations:', recommendations);
}