@decibeltrade/sdk 0.1.1

package/decibel_transactions.md

@@ -0,0 +1,1049 @@
+# Decibel Smart Contract Transaction Guide
+
+This guide shows developers exactly how to interact with Decibel's smart contracts on Aptos, with all necessary imports, configurations, and transaction patterns.
+
+## Table of Contents
+
+1. [Required Dependencies](#required-dependencies)
+2. [Configuration Setup](#configuration-setup)
+3. [Core Transaction Infrastructure](#core-transaction-infrastructure)
+4. [Account Management Transactions](#account-management-transactions)
+5. [Order Management Transactions](#order-management-transactions)
+6. [Position Management Transactions](#position-management-transactions)
+7. [Advanced Features](#advanced-features)
+8. [Complete Working Examples](#complete-working-examples)
+
+## Required Dependencies
+
+First, install the necessary packages:
+
+```bash
+npm install @aptos-labs/ts-sdk zod
+```
+
+## Configuration Setup
+
+### 1. Network Configuration
+
+```typescript path=null start=null
+import {
+  Account,
+  AccountAddress,
+  AccountAuthenticator,
+  Aptos,
+  AptosConfig,
+  CommittedTransactionResponse,
+  InputGenerateTransactionPayloadData,
+  MoveString,
+  Network,
+  PendingTransactionResponse,
+  SimpleTransaction,
+  createObjectAddress,
+} from "@aptos-labs/ts-sdk";
+
+// Configuration interfaces
+interface DecibelConfig {
+  network: Network;
+  fullnodeUrl: string;
+  tradingHttpUrl: string;
+  tradingWsUrl: string;
+  gasStationUrl: string;
+  deployment: Deployment;
+}
+
+interface Deployment {
+  package: string; // Smart contract package address
+  usdc: string; // USDC token address
+  testc: string; // Test collateral address
+  perpEngineGlobal: string; // Global perpetual engine address
+}
+
+// Utility functions for address generation
+function getUsdcAddress(publisherAddr: string) {
+  return createObjectAddress(
+    AccountAddress.fromString(publisherAddr),
+    new TextEncoder().encode("USDC"),
+  );
+}
+
+function getPerpEngineGlobalAddress(publisherAddr: string) {
+  return createObjectAddress(
+    AccountAddress.fromString(publisherAddr),
+    new TextEncoder().encode("GlobalPerpEngine"),
+  );
+}
+
+// Network configurations
+const NETNA_PACKAGE = "0xb8a5788314451ce4d2fbbad32e1bad88d4184b73943b7fe5166eab93cf1a5a95";
+
+const NETNA_CONFIG: DecibelConfig = {
+  network: Network.CUSTOM,
+  fullnodeUrl: "https://api.netna.staging.aptoslabs.com/v1",
+  tradingHttpUrl: "https://api.netna.aptoslabs.com/decibel",
+  tradingWsUrl: "wss://api.netna.aptoslabs.com/decibel/ws",
+  gasStationUrl: "https://fee-payer-dev-netna-us-central1-410192433417.us-central1.run.app",
+  deployment: {
+    package: NETNA_PACKAGE,
+    usdc: getUsdcAddress(NETNA_PACKAGE).toString(),
+    testc: getUsdcAddress(NETNA_PACKAGE).toString(), // Using same for test
+    perpEngineGlobal: getPerpEngineGlobalAddress(NETNA_PACKAGE).toString(),
+  },
+};
+```
+
+### 2. Order Types and Constants
+
+```typescript path=null start=null
+// Time in Force options for orders
+const TimeInForce = {
+  GoodTillCanceled: 0, // Order stays active until canceled
+  PostOnly: 1, // Order only adds liquidity (becomes maker)
+  ImmediateOrCancel: 2, // Execute immediately or cancel remainder
+} as const;
+type TimeInForce = (typeof TimeInForce)[keyof typeof TimeInForce];
+
+// Order result interface
+interface PlaceOrderResult {
+  success: boolean;
+  orderId?: string; // Extracted from transaction events
+  transactionHash: string | null;
+  error?: string;
+}
+
+// Order event structure (returned in transaction events)
+interface OrderEvent {
+  order_id: string; // The generated order ID
+  user: string; // Subaccount address that placed the order
+  market: string; // Market address
+  price: string; // Order price
+  orig_size: string; // Original order size
+  remaining_size: string; // Remaining unfilled size
+  is_bid: boolean; // True for buy orders, false for sell
+  // ... other fields
+}
+```
+
+## Core Transaction Infrastructure
+
+### 1. Base Transaction Manager
+
+```typescript path=null start=null
+class DecibelTransactionManager {
+  private aptos: Aptos;
+  private config: DecibelConfig;
+  private skipSimulate: boolean;
+  private noFeePayer: boolean;
+
+  constructor(
+    config: DecibelConfig,
+    private account: Account,
+    options?: {
+      skipSimulate?: boolean;
+      noFeePayer?: boolean;
+      nodeApiKey?: string;
+    },
+  ) {
+    this.config = config;
+    this.skipSimulate = options?.skipSimulate ?? false;
+    this.noFeePayer = options?.noFeePayer ?? false;
+
+    // Initialize Aptos client
+    const aptosConfig = new AptosConfig({
+      network: config.network,
+      fullnode: config.fullnodeUrl,
+      clientConfig: { API_KEY: options?.nodeApiKey },
+    });
+    this.aptos = new Aptos(aptosConfig);
+  }
+
+  /**
+   * Simulate transaction to get gas estimates
+   */
+  private async getSimulatedTransaction(
+    payload: InputGenerateTransactionPayloadData,
+    sender: AccountAddress,
+  ): Promise<SimpleTransaction> {
+    const transaction = await this.aptos.transaction.build.simple({
+      sender,
+      data: payload,
+    });
+
+    const [simulationResult] = await this.aptos.transaction.simulate.simple({
+      transaction,
+      options: {
+        estimateMaxGasAmount: true,
+        estimateGasUnitPrice: true,
+      },
+    });
+
+    if (!simulationResult?.max_gas_amount || !simulationResult?.gas_unit_price) {
+      throw new Error("Transaction simulation failed - no gas estimates returned");
+    }
+
+    // Build transaction with gas estimates
+    return await this.aptos.transaction.build.simple({
+      sender,
+      data: payload,
+      options: {
+        maxGasAmount: Number(simulationResult.max_gas_amount),
+        gasUnitPrice: Number(simulationResult.gas_unit_price),
+      },
+    });
+  }
+
+  /**
+   * Submit transaction with optional fee payer support
+   */
+  private async submitTransaction(
+    transaction: SimpleTransaction,
+    senderAuthenticator: AccountAuthenticator,
+  ): Promise<PendingTransactionResponse> {
+    if (this.noFeePayer) {
+      // Submit without fee payer (user pays gas)
+      return await this.aptos.transaction.submit.simple({
+        transaction,
+        senderAuthenticator,
+      });
+    } else {
+      // Submit with fee payer (Decibel pays gas)
+      return await this.submitFeePaidTransaction(transaction, senderAuthenticator);
+    }
+  }
+
+  /**
+   * Submit transaction using Decibel's fee payer service
+   */
+  private async submitFeePaidTransaction(
+    transaction: SimpleTransaction,
+    senderAuthenticator: AccountAuthenticator,
+  ): Promise<PendingTransactionResponse> {
+    const signatureBcs = Array.from(senderAuthenticator.bcsToBytes());
+    const transactionBcs = Array.from(transaction.rawTransaction.bcsToBytes());
+
+    const response = await fetch(this.config.gasStationUrl + "/transactions", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        signature: signatureBcs,
+        transaction: transactionBcs,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Fee payer service error: ${response.status}`);
+    }
+
+    return (await response.json()) as PendingTransactionResponse;
+  }
+
+  /**
+   * Main method to send any transaction to the blockchain
+   */
+  async sendTransaction(
+    payload: InputGenerateTransactionPayloadData,
+    accountOverride?: Account,
+  ): Promise<CommittedTransactionResponse> {
+    const signer = accountOverride ?? this.account;
+    const sender = signer.accountAddress;
+
+    let transaction: SimpleTransaction;
+
+    if (!this.skipSimulate) {
+      // Get gas estimates through simulation
+      transaction = await this.getSimulatedTransaction(payload, sender);
+    } else {
+      // Build transaction without simulation
+      const withFeePayer = !this.noFeePayer;
+      transaction = await this.aptos.transaction.build.simple({
+        sender,
+        data: payload,
+        withFeePayer,
+      });
+    }
+
+    // Sign the transaction
+    const senderAuthenticator = this.aptos.transaction.sign({
+      signer,
+      transaction,
+    });
+
+    // Submit and wait for confirmation
+    const pendingTransaction = await this.submitTransaction(transaction, senderAuthenticator);
+    return await this.aptos.waitForTransaction({
+      transactionHash: pendingTransaction.hash,
+    });
+  }
+}
+```
+
+### 2. Utility Functions
+
+```typescript path=null start=null
+/**
+ * Get market address from market name
+ */
+function getMarketAddress(marketName: string, perpEngineGlobalAddr: string): AccountAddress {
+  const marketNameBytes = new MoveString(marketName).bcsToBytes();
+  return createObjectAddress(AccountAddress.fromString(perpEngineGlobalAddr), marketNameBytes);
+}
+
+/**
+ * Get primary subaccount address for a user account
+ */
+function getPrimarySubaccountAddress(userAddress: AccountAddress): string {
+  const seed = new TextEncoder().encode("decibel_dex_primary");
+  return createObjectAddress(userAddress, seed).toString();
+}
+
+/**
+ * Extract order ID from transaction events
+ */
+function extractOrderIdFromTransaction(
+  txResponse: CommittedTransactionResponse,
+  subaccountAddr: string,
+): string | null {
+  try {
+    if ("events" in txResponse && Array.isArray(txResponse.events)) {
+      for (const event of txResponse.events) {
+        // Look for OrderEvent from the market module
+        if (event.type.includes("::market_types::OrderEvent")) {
+          const orderEvent = event.data as OrderEvent;
+          // Verify this event is from the correct subaccount
+          if (orderEvent.user === subaccountAddr) {
+            return orderEvent.order_id;
+          }
+        }
+      }
+    }
+    return null;
+  } catch (error) {
+    console.error("Error extracting order ID:", error);
+    return null;
+  }
+}
+```
+
+## Account Management Transactions
+
+### 1. Create Subaccount
+
+```typescript path=null start=null
+/**
+ * Create a new trading subaccount
+ * Each user can have multiple subaccounts for different trading strategies
+ */
+async function createSubaccount(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+): Promise<CommittedTransactionResponse> {
+  return await transactionManager.sendTransaction({
+    function: `${config.deployment.package}::dex_accounts::create_new_subaccount`,
+    typeArguments: [],
+    functionArguments: [],
+  });
+}
+```
+
+### 2. Deposit Collateral
+
+```typescript path=null start=null
+/**
+ * Deposit USDC collateral to a subaccount
+ * @param amount Amount in smallest unit (e.g., 1000000 = 1 USDC if 6 decimals)
+ * @param subaccountAddr Optional specific subaccount, uses primary if not provided
+ */
+async function depositCollateral(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  amount: number,
+  subaccountAddr: string,
+): Promise<CommittedTransactionResponse> {
+  // Deposit to specific subaccount
+  return await transactionManager.sendTransaction({
+    function: `${config.deployment.package}::dex_accounts::deposit_to_subaccount_at`,
+    typeArguments: [],
+    functionArguments: [subaccountAddr, config.deployment.usdc, amount],
+  });
+}
+```
+
+### 3. Withdraw Collateral
+
+```typescript path=null start=null
+/**
+ * Withdraw collateral from a subaccount
+ * @param amount Amount in smallest unit to withdraw
+ * @param subaccountAddr Subaccount to withdraw from (uses primary if not provided)
+ */
+async function withdrawCollateral(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  amount: number,
+  subaccountAddr?: string,
+): Promise<CommittedTransactionResponse> {
+  const subaccount =
+    subaccountAddr ?? getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+  return await transactionManager.sendTransaction({
+    function: `${config.deployment.package}::dex_accounts::withdraw_from_subaccount`,
+    typeArguments: [],
+    functionArguments: [subaccount, config.deployment.usdc, amount],
+  });
+}
+```
+
+### 4. Configure Market Settings
+
+```typescript path=null start=null
+/**
+ * Configure user settings for a specific market
+ * @param marketAddr The market address to configure
+ * @param subaccountAddr The subaccount address
+ * @param isCross Whether to use cross-margin mode (vs isolated)
+ * @param userLeverage Leverage in basis points (1000 = 10x leverage)
+ */
+async function configureMarketSettings(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  marketAddr: string,
+  subaccountAddr: string,
+  isCross: boolean,
+  userLeverage: number,
+): Promise<CommittedTransactionResponse> {
+  return await transactionManager.sendTransaction({
+    function: `${config.deployment.package}::dex_accounts::configure_user_settings_for_market`,
+    typeArguments: [],
+    functionArguments: [subaccountAddr, marketAddr, isCross, userLeverage],
+  });
+}
+```
+
+## Order Management Transactions
+
+### 1. Place Order
+
+```typescript path=null start=null
+/**
+ * Place a trading order on the exchange
+ */
+async function placeOrder(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    marketName: string; // e.g., "BTC-USD"
+    price: number; // Price in quote currency
+    size: number; // Size in base currency
+    isBuy: boolean; // true for buy, false for sell
+    timeInForce: TimeInForce; // Order execution type
+    isReduceOnly: boolean; // true to only reduce position size
+    clientOrderId?: number; // Optional client-assigned order ID
+    stopPrice?: number; // Optional stop price for stop orders
+    tpTriggerPrice?: number; // Take profit trigger price
+    tpLimitPrice?: number; // Take profit limit price
+    slTriggerPrice?: number; // Stop loss trigger price
+    slLimitPrice?: number; // Stop loss limit price
+    builderAddr?: string; // Optional builder/referrer address
+    builderFee?: number; // Builder fee in basis points
+    subaccountAddr?: string; // Optional subaccount (uses primary if not provided)
+    accountOverride?: Account; // Optional account override (for session accounts)
+  },
+): Promise<PlaceOrderResult> {
+  try {
+    // Get market address from name
+    const marketAddr = getMarketAddress(params.marketName, config.deployment.perpEngineGlobal);
+
+    // Use primary subaccount if none provided
+    const subaccountAddr =
+      params.subaccountAddr ??
+      getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+    // Send the transaction
+    const txResponse = await transactionManager.sendTransaction(
+      {
+        function: `${config.deployment.package}::dex_accounts::place_order_to_subaccount`,
+        typeArguments: [],
+        functionArguments: [
+          subaccountAddr,
+          marketAddr.toString(),
+          params.price,
+          params.size,
+          params.isBuy,
+          params.timeInForce,
+          params.isReduceOnly,
+          params.clientOrderId,
+          params.stopPrice,
+          params.tpTriggerPrice,
+          params.tpLimitPrice,
+          params.slTriggerPrice,
+          params.slLimitPrice,
+          params.builderAddr,
+          params.builderFee,
+        ],
+      },
+      params.accountOverride,
+    );
+
+    // Extract order ID from transaction events
+    const orderId = extractOrderIdFromTransaction(txResponse, subaccountAddr);
+
+    return {
+      success: true,
+      orderId: orderId || undefined,
+      transactionHash: txResponse.hash,
+    };
+  } catch (error) {
+    console.error("Error placing order:", error);
+    return {
+      success: false,
+      transactionHash: null,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+```
+
+### 2. Cancel Order
+
+```typescript path=null start=null
+/**
+ * Cancel an existing order by order ID
+ */
+async function cancelOrder(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    orderId: number;
+    marketName?: string; // Either marketName OR marketAddr must be provided
+    marketAddr?: string;
+    subaccountAddr?: string;
+    accountOverride?: Account;
+  },
+): Promise<CommittedTransactionResponse> {
+  // Get market address
+  const marketAddr =
+    params.marketAddr ??
+    (params.marketName
+      ? getMarketAddress(params.marketName, config.deployment.perpEngineGlobal).toString()
+      : "");
+
+  if (!marketAddr) {
+    throw new Error("Either marketName or marketAddr must be provided");
+  }
+
+  const subaccountAddr =
+    params.subaccountAddr ?? getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+  return await transactionManager.sendTransaction(
+    {
+      function: `${config.deployment.package}::dex_accounts::cancel_order_to_subaccount`,
+      typeArguments: [],
+      functionArguments: [subaccountAddr, params.orderId, marketAddr],
+    },
+    params.accountOverride,
+  );
+}
+```
+
+### 3. Cancel Order by Client ID
+
+```typescript path=null start=null
+/**
+ * Cancel an order using the client-assigned order ID
+ */
+async function cancelClientOrder(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    clientOrderId: number;
+    marketName: string;
+    subaccountAddr?: string;
+    accountOverride?: Account;
+  },
+): Promise<CommittedTransactionResponse> {
+  const marketAddr = getMarketAddress(params.marketName, config.deployment.perpEngineGlobal);
+  const subaccountAddr =
+    params.subaccountAddr ?? getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+  return await transactionManager.sendTransaction(
+    {
+      function: `${config.deployment.package}::dex_accounts::cancel_client_order_to_subaccount`,
+      typeArguments: [],
+      functionArguments: [subaccountAddr, params.clientOrderId, marketAddr.toString()],
+    },
+    params.accountOverride,
+  );
+}
+```
+
+### 4. TWAP (Time-Weighted Average Price) Orders
+
+```typescript path=null start=null
+/**
+ * Place a TWAP order that executes over time
+ * @param twapFrequencySeconds How often to execute sub-orders (in seconds)
+ * @param twapDurationSeconds Total duration for the TWAP order (in seconds)
+ */
+async function placeTwapOrder(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    marketName: string;
+    size: number; // Total size to be executed over time
+    isBuy: boolean;
+    isReduceOnly: boolean;
+    twapFrequencySeconds: number; // e.g., 60 = execute every minute
+    twapDurationSeconds: number; // e.g., 3600 = over 1 hour
+    subaccountAddr?: string;
+    accountOverride?: Account;
+  },
+): Promise<CommittedTransactionResponse> {
+  const marketAddr = getMarketAddress(params.marketName, config.deployment.perpEngineGlobal);
+  const subaccountAddr =
+    params.subaccountAddr ?? getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+  return await transactionManager.sendTransaction(
+    {
+      function: `${config.deployment.package}::dex_accounts::place_twap_order_to_subaccount`,
+      typeArguments: [],
+      functionArguments: [
+        subaccountAddr,
+        marketAddr.toString(),
+        params.size,
+        params.isBuy,
+        params.isReduceOnly,
+        params.twapFrequencySeconds,
+        params.twapDurationSeconds,
+      ],
+    },
+    params.accountOverride,
+  );
+}
+```
+
+## Position Management Transactions
+
+### 1. Place Take-Profit/Stop-Loss Orders
+
+```typescript path=null start=null
+/**
+ * Place TP/SL orders for an existing position
+ */
+async function placeTpSlOrderForPosition(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    marketAddr: string;
+    tpTriggerPrice?: number; // Take profit trigger price
+    tpLimitPrice?: number; // Take profit limit price
+    tpSize?: number; // Take profit size (partial or full position)
+    slTriggerPrice?: number; // Stop loss trigger price
+    slLimitPrice?: number; // Stop loss limit price
+    slSize?: number; // Stop loss size
+    subaccountAddr?: string;
+    accountOverride?: Account;
+  },
+): Promise<CommittedTransactionResponse> {
+  const subaccountAddr =
+    params.subaccountAddr ?? getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+  return await transactionManager.sendTransaction(
+    {
+      function: `${config.deployment.package}::dex_accounts::place_tp_sl_order_for_position`,
+      typeArguments: [],
+      functionArguments: [
+        subaccountAddr,
+        params.marketAddr,
+        params.tpTriggerPrice,
+        params.tpLimitPrice,
+        params.tpSize,
+        params.slTriggerPrice,
+        params.slLimitPrice,
+        params.slSize,
+      ],
+    },
+    params.accountOverride,
+  );
+}
+```
+
+### 2. Update Take-Profit/Stop-Loss Orders
+
+```typescript path=null start=null
+/**
+ * Update existing TP/SL orders for a position
+ */
+async function updateTpSlOrderForPosition(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    marketAddr: string;
+    prevOrderId: string; // ID of the previous TP/SL order to update
+    tpTriggerPrice?: number;
+    tpLimitPrice?: number;
+    tpSize?: number;
+    slTriggerPrice?: number;
+    slLimitPrice?: number;
+    slSize?: number;
+    subaccountAddr?: string;
+    accountOverride?: Account;
+  },
+): Promise<CommittedTransactionResponse> {
+  const subaccountAddr =
+    params.subaccountAddr ?? getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+  return await transactionManager.sendTransaction(
+    {
+      function: `${config.deployment.package}::dex_accounts::update_tp_sl_order_for_position`,
+      typeArguments: [],
+      functionArguments: [
+        subaccountAddr,
+        Number(params.prevOrderId),
+        params.marketAddr,
+        params.tpTriggerPrice,
+        params.tpLimitPrice,
+        params.tpSize,
+        params.slTriggerPrice,
+        params.slLimitPrice,
+        params.slSize,
+      ],
+    },
+    params.accountOverride,
+  );
+}
+```
+
+### 3. Cancel Take-Profit/Stop-Loss Orders
+
+```typescript path=null start=null
+/**
+ * Cancel TP/SL orders for a position
+ */
+async function cancelTpSlOrderForPosition(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    marketName: string;
+    orderId: number;
+    subaccountAddr?: string;
+    accountOverride?: Account;
+  },
+): Promise<CommittedTransactionResponse> {
+  const marketAddr = getMarketAddress(params.marketName, config.deployment.perpEngineGlobal);
+  const subaccountAddr =
+    params.subaccountAddr ?? getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+  return await transactionManager.sendTransaction(
+    {
+      function: `${config.deployment.package}::dex_accounts::cancel_tp_sl_order_for_position`,
+      typeArguments: [],
+      functionArguments: [subaccountAddr, marketAddr.toString(), params.orderId],
+    },
+    params.accountOverride,
+  );
+}
+```
+
+## Advanced Features
+
+### 1. Trading Delegation
+
+```typescript path=null start=null
+/**
+ * Delegate trading permissions to another account
+ * This allows the delegate account to trade on behalf of the subaccount
+ */
+async function delegateTradingTo(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    accountToDelegateTo: string; // Address to delegate trading to
+    subaccountAddr?: string;
+  },
+): Promise<CommittedTransactionResponse> {
+  const subaccountAddr =
+    params.subaccountAddr ?? getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+  return await transactionManager.sendTransaction({
+    function: `${config.deployment.package}::dex_accounts::delegate_trading_to_for_subaccount`,
+    typeArguments: [],
+    functionArguments: [subaccountAddr, params.accountToDelegateTo],
+  });
+}
+
+/**
+ * Revoke trading delegation from an account
+ */
+async function revokeDelegation(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    accountToRevoke: string; // Address to revoke delegation from
+    subaccountAddr?: string;
+  },
+): Promise<CommittedTransactionResponse> {
+  const subaccountAddr =
+    params.subaccountAddr ?? getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+  return await transactionManager.sendTransaction({
+    function: `${config.deployment.package}::dex_accounts::revoke_delegation`,
+    typeArguments: [],
+    functionArguments: [subaccountAddr, params.accountToRevoke],
+  });
+}
+```
+
+## Complete Working Examples
+
+### 1. Basic Trading Example
+
+```typescript path=null start=null
+async function basicTradingExample() {
+  // 1. Set up account and transaction manager
+  const privateKey = "your-private-key-here";
+  const account = Account.fromPrivateKey({ privateKey });
+  const transactionManager = new DecibelTransactionManager(NETNA_CONFIG, account, {
+    skipSimulate: false, // Use simulation for gas estimation
+    noFeePayer: false, // Use Decibel's fee payer service
+  });
+
+  try {
+    // 2. Create a subaccount
+    console.log("Creating subaccount...");
+    const createTx = await createSubaccount(transactionManager, NETNA_CONFIG);
+    console.log("Subaccount created:", createTx.hash);
+
+    // 3. Get the primary subaccount address
+    const subaccountAddr = getPrimarySubaccountAddress(account.accountAddress);
+    console.log("Primary subaccount address:", subaccountAddr);
+
+    // 4. Deposit collateral (1000 USDC = 1000000000 if 6 decimals)
+    console.log("Depositing collateral...");
+    const depositTx = await depositCollateral(
+      transactionManager,
+      NETNA_CONFIG,
+      1000000000,
+      subaccountAddr,
+    );
+    console.log("Deposit successful:", depositTx.hash);
+
+    // 5. Configure market settings for BTC-USD
+    const btcMarketAddr = getMarketAddress("BTC-USD", NETNA_CONFIG.deployment.perpEngineGlobal);
+    console.log("Configuring market settings...");
+    const configTx = await configureMarketSettings(
+      transactionManager,
+      NETNA_CONFIG,
+      btcMarketAddr.toString(),
+      subaccountAddr,
+      true, // Use cross-margin
+      1000, // 10x leverage (1000 basis points)
+    );
+    console.log("Market configured:", configTx.hash);
+
+    // 6. Place a limit buy order for 0.1 BTC at $45,000
+    console.log("Placing buy order...");
+    const orderResult = await placeOrder(transactionManager, NETNA_CONFIG, {
+      marketName: "BTC-USD",
+      price: 45000,
+      size: 0.1,
+      isBuy: true,
+      timeInForce: TimeInForce.GoodTillCanceled,
+      isReduceOnly: false,
+      subaccountAddr,
+    });
+
+    if (orderResult.success) {
+      console.log("Order placed successfully!");
+      console.log("Order ID:", orderResult.orderId);
+      console.log("Transaction:", orderResult.transactionHash);
+
+      // 7. Cancel the order (example)
+      if (orderResult.orderId) {
+        console.log("Canceling order...");
+        const cancelTx = await cancelOrder(transactionManager, NETNA_CONFIG, {
+          orderId: parseInt(orderResult.orderId),
+          marketName: "BTC-USD",
+          subaccountAddr,
+        });
+        console.log("Order canceled:", cancelTx.hash);
+      }
+    } else {
+      console.error("Order failed:", orderResult.error);
+    }
+  } catch (error) {
+    console.error("Error in trading example:", error);
+  }
+}
+```
+
+### 2. Advanced Position Management Example
+
+```typescript path=null start=null
+async function advancedPositionExample() {
+  const account = Account.fromPrivateKey({ privateKey: "your-private-key-here" });
+  const transactionManager = new DecibelTransactionManager(NETNA_CONFIG, account);
+  const subaccountAddr = getPrimarySubaccountAddress(account.accountAddress);
+
+  try {
+    // 1. Place a market buy order (using IOC with high price)
+    console.log("Opening position with market order...");
+    const marketOrderResult = await placeOrder(transactionManager, NETNA_CONFIG, {
+      marketName: "BTC-USD",
+      price: 50000, // High price to ensure execution
+      size: 1.0,
+      isBuy: true,
+      timeInForce: TimeInForce.ImmediateOrCancel,
+      isReduceOnly: false,
+      subaccountAddr,
+    });
+
+    if (!marketOrderResult.success) {
+      throw new Error("Failed to open position: " + marketOrderResult.error);
+    }
+
+    console.log("Position opened:", marketOrderResult.transactionHash);
+
+    // 2. Set up take-profit and stop-loss orders
+    const btcMarketAddr = getMarketAddress("BTC-USD", NETNA_CONFIG.deployment.perpEngineGlobal);
+
+    console.log("Setting up TP/SL orders...");
+    const tpSlTx = await placeTpSlOrderForPosition(transactionManager, NETNA_CONFIG, {
+      marketAddr: btcMarketAddr.toString(),
+      tpTriggerPrice: 52000, // Take profit at $52,000
+      tpLimitPrice: 51900, // Limit price for TP order
+      tpSize: 0.5, // Close half position
+      slTriggerPrice: 44000, // Stop loss at $44,000
+      slLimitPrice: 44100, // Limit price for SL order
+      slSize: 1.0, // Close entire position
+      subaccountAddr,
+    });
+
+    console.log("TP/SL orders placed:", tpSlTx.hash);
+
+    // 3. Place a TWAP order to scale into a larger position
+    console.log("Starting TWAP order...");
+    const twapTx = await placeTwapOrder(transactionManager, NETNA_CONFIG, {
+      marketName: "BTC-USD",
+      size: 2.0, // Buy 2 BTC total
+      isBuy: true,
+      isReduceOnly: false,
+      twapFrequencySeconds: 300, // Every 5 minutes
+      twapDurationSeconds: 3600, // Over 1 hour
+      subaccountAddr,
+    });
+
+    console.log("TWAP order started:", twapTx.hash);
+  } catch (error) {
+    console.error("Error in position management:", error);
+  }
+}
+```
+
+### 3. Session Account Example (for dApps)
+
+```typescript path=null start=null
+/**
+ * Example of using session accounts for dApp integrations
+ * The main account delegates to a session account with limited permissions
+ */
+async function sessionAccountExample() {
+  // Main user account
+  const mainAccount = Account.fromPrivateKey({ privateKey: "user-private-key" });
+  const transactionManager = new DecibelTransactionManager(NETNA_CONFIG, mainAccount);
+  const subaccountAddr = getPrimarySubaccountAddress(mainAccount.accountAddress);
+
+  // Generate a temporary session account
+  const sessionAccount = Account.generate();
+  console.log("Generated session account:", sessionAccount.accountAddress.toString());
+
+  try {
+    // 1. Delegate trading permissions to session account
+    console.log("Delegating trading permissions...");
+    const delegateTx = await delegateTradingTo(transactionManager, NETNA_CONFIG, {
+      accountToDelegateTo: sessionAccount.accountAddress.toString(),
+      subaccountAddr,
+    });
+    console.log("Delegation successful:", delegateTx.hash);
+
+    // 2. Use session account to place orders
+    console.log("Placing order with session account...");
+    const orderResult = await placeOrder(transactionManager, NETNA_CONFIG, {
+      marketName: "ETH-USD",
+      price: 3000,
+      size: 5.0,
+      isBuy: true,
+      timeInForce: TimeInForce.PostOnly,
+      isReduceOnly: false,
+      subaccountAddr,
+      accountOverride: sessionAccount, // Use session account to sign
+    });
+
+    if (orderResult.success) {
+      console.log("Session order placed:", orderResult.orderId);
+    }
+
+    // 3. Later, revoke session account permissions
+    console.log("Revoking session permissions...");
+    const revokeTx = await revokeDelegation(transactionManager, NETNA_CONFIG, {
+      accountToRevoke: sessionAccount.accountAddress.toString(),
+      subaccountAddr,
+    });
+    console.log("Permissions revoked:", revokeTx.hash);
+  } catch (error) {
+    console.error("Error in session account example:", error);
+  }
+}
+```
+
+## Best Practices and Notes
+
+### 1. Error Handling
+
+Always wrap transaction calls in try-catch blocks and handle different types of errors:
+
+```typescript path=null start=null
+async function handleTransactionErrors() {
+  try {
+    const result = await placeOrder(/* parameters */);
+    if (!result.success) {
+      // Handle business logic errors
+      console.error("Order placement failed:", result.error);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.message.includes("INSUFFICIENT_BALANCE")) {
+        console.error("Not enough collateral to place order");
+      } else if (error.message.includes("TRANSACTION_EXPIRED")) {
+        console.error("Transaction took too long - retry with higher gas");
+      } else {
+        console.error("Unexpected error:", error.message);
+      }
+    }
+  }
+}
+```
+
+### 2. Gas Management
+
+- Use `skipSimulate: false` for gas estimation in production
+- Set appropriate gas limits for complex transactions
+- Monitor gas prices and adjust accordingly
+
+### 3. Subaccount Management
+
+- Use primary subaccount for simple use cases
+- Create separate subaccounts for different strategies
+- Always verify subaccount addresses before transactions
+
+### 4. Market Address Handling
+
+- Cache market addresses to avoid repeated calculations
+- Verify market names are correct before generating addresses
+- Handle market address resolution errors gracefully
+
+### 5. Order Management
+
+- Store order IDs for later cancellation
+- Use client order IDs for easier tracking
+- Implement proper order status monitoring