@decibeltrade/sdk 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decibeltrade/sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

package/readme.md

@@ -872,6 +872,621 @@ const bot = new TradingBot("your-private-key", "your-subaccount-address");
 bot.start();
 ```
 
+## Smart Contract Transactions
+
+For developers who need direct access to Decibel's smart contracts, this section shows how to build and submit transactions directly using the Aptos SDK.
+
+### Core Transaction Infrastructure
+
+#### Base Transaction Manager
+
+```typescript
+import {
+  Account,
+  AccountAddress,
+  AccountAuthenticator,
+  Aptos,
+  AptosConfig,
+  CommittedTransactionResponse,
+  InputGenerateTransactionPayloadData,
+  MoveString,
+  Network,
+  PendingTransactionResponse,
+  SimpleTransaction,
+  createObjectAddress,
+} from "@aptos-labs/ts-sdk";
+
+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;
+
+    const aptosConfig = new AptosConfig({
+      network: config.network,
+      fullnode: config.fullnodeUrl,
+      clientConfig: { API_KEY: options?.nodeApiKey },
+    });
+    this.aptos = new Aptos(aptosConfig);
+  }
+
+  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");
+    }
+
+    return await this.aptos.transaction.build.simple({
+      sender,
+      data: payload,
+      options: {
+        maxGasAmount: Number(simulationResult.max_gas_amount),
+        gasUnitPrice: Number(simulationResult.gas_unit_price),
+      },
+    });
+  }
+
+  private async submitTransaction(
+    transaction: SimpleTransaction,
+    senderAuthenticator: AccountAuthenticator,
+  ): Promise<PendingTransactionResponse> {
+    if (this.noFeePayer) {
+      return await this.aptos.transaction.submit.simple({
+        transaction,
+        senderAuthenticator,
+      });
+    } else {
+      return await this.submitFeePaidTransaction(transaction, senderAuthenticator);
+    }
+  }
+
+  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;
+  }
+
+  async sendTransaction(
+    payload: InputGenerateTransactionPayloadData,
+    accountOverride?: Account,
+  ): Promise<CommittedTransactionResponse> {
+    const signer = accountOverride ?? this.account;
+    const sender = signer.accountAddress;
+
+    let transaction: SimpleTransaction;
+
+    if (!this.skipSimulate) {
+      transaction = await this.getSimulatedTransaction(payload, sender);
+    } else {
+      const withFeePayer = !this.noFeePayer;
+      transaction = await this.aptos.transaction.build.simple({
+        sender,
+        data: payload,
+        withFeePayer,
+      });
+    }
+
+    const senderAuthenticator = this.aptos.transaction.sign({
+      signer,
+      transaction,
+    });
+
+    const pendingTransaction = await this.submitTransaction(transaction, senderAuthenticator);
+    return await this.aptos.waitForTransaction({
+      transactionHash: pendingTransaction.hash,
+    });
+  }
+}
+```
+
+### Utility Functions
+
+```typescript
+/**
+ * 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) {
+        if (event.type.includes("::market_types::OrderEvent")) {
+          const orderEvent = event.data as any;
+          if (orderEvent.user === subaccountAddr) {
+            return orderEvent.order_id;
+          }
+        }
+      }
+    }
+    return null;
+  } catch (error) {
+    console.error("Error extracting order ID:", error);
+    return null;
+  }
+}
+```
+
+### Account Management Transactions
+
+#### Create Subaccount
+
+```typescript
+async function createSubaccount(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+): Promise<CommittedTransactionResponse> {
+  return await transactionManager.sendTransaction({
+    function: `${config.deployment.package}::dex_accounts::create_new_subaccount`,
+    typeArguments: [],
+    functionArguments: [],
+  });
+}
+```
+
+#### Deposit Collateral
+
+```typescript
+async function depositCollateral(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  amount: number,
+  subaccountAddr: string,
+): Promise<CommittedTransactionResponse> {
+  return await transactionManager.sendTransaction({
+    function: `${config.deployment.package}::dex_accounts::deposit_to_subaccount_at`,
+    typeArguments: [],
+    functionArguments: [subaccountAddr, config.deployment.usdc, amount],
+  });
+}
+```
+
+#### Withdraw Collateral
+
+```typescript
+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],
+  });
+}
+```
+
+#### Configure Market Settings
+
+```typescript
+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
+
+#### Place Order
+
+```typescript
+interface PlaceOrderResult {
+  success: boolean;
+  orderId?: string;
+  transactionHash: string | null;
+  error?: string;
+}
+
+async function placeOrder(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    marketName: string;
+    price: number;
+    size: number;
+    isBuy: boolean;
+    timeInForce: number;
+    isReduceOnly: boolean;
+    clientOrderId?: number;
+    stopPrice?: number;
+    tpTriggerPrice?: number;
+    tpLimitPrice?: number;
+    slTriggerPrice?: number;
+    slLimitPrice?: number;
+    builderAddr?: string;
+    builderFee?: number;
+    subaccountAddr?: string;
+    accountOverride?: Account;
+  },
+): Promise<PlaceOrderResult> {
+  try {
+    const marketAddr = getMarketAddress(params.marketName, config.deployment.perpEngineGlobal);
+    const subaccountAddr =
+      params.subaccountAddr ??
+      getPrimarySubaccountAddress(transactionManager.account.accountAddress);
+
+    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,
+    );
+
+    const orderId = extractOrderIdFromTransaction(txResponse, subaccountAddr);
+
+    return {
+      success: true,
+      orderId: orderId || undefined,
+      transactionHash: txResponse.hash,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      transactionHash: null,
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+}
+```
+
+#### Cancel Order
+
+```typescript
+async function cancelOrder(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    orderId: number;
+    marketName?: string;
+    marketAddr?: string;
+    subaccountAddr?: string;
+    accountOverride?: Account;
+  },
+): Promise<CommittedTransactionResponse> {
+  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,
+  );
+}
+```
+
+#### Place TWAP Order
+
+```typescript
+async function placeTwapOrder(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    marketName: string;
+    size: number;
+    isBuy: boolean;
+    isReduceOnly: boolean;
+    twapFrequencySeconds: number;
+    twapDurationSeconds: 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::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
+
+#### Place TP/SL Order
+
+```typescript
+async function placeTpSlOrderForPosition(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    marketAddr: string;
+    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::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,
+  );
+}
+```
+
+### Trading Delegation
+
+#### Delegate Trading
+
+```typescript
+async function delegateTradingTo(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    accountToDelegateTo: string;
+    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 Delegation
+
+```typescript
+async function revokeDelegation(
+  transactionManager: DecibelTransactionManager,
+  config: DecibelConfig,
+  params: {
+    accountToRevoke: string;
+    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 Example
+
+```typescript
+import { Account } from "@aptos-labs/ts-sdk";
+
+async function basicTradingExample() {
+  const privateKey = "your-private-key-here";
+  const account = Account.fromPrivateKey({ privateKey });
+  const transactionManager = new DecibelTransactionManager(NETNA_CONFIG, account, {
+    skipSimulate: false,
+    noFeePayer: false,
+  });
+
+  try {
+    // Create a subaccount
+    console.log("Creating subaccount...");
+    const createTx = await createSubaccount(transactionManager, NETNA_CONFIG);
+    console.log("Subaccount created:", createTx.hash);
+
+    // Get the primary subaccount address
+    const subaccountAddr = getPrimarySubaccountAddress(account.accountAddress);
+    console.log("Primary subaccount address:", subaccountAddr);
+
+    // 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);
+
+    // 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);
+
+    // 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);
+
+      // Cancel the order
+      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);
+  }
+}
+```
+
+### Best Practices
+
+1. **Error Handling**: Always wrap transaction calls in try-catch blocks and handle different types of errors appropriately.
+
+2. **Gas Management**: Use `skipSimulate: false` for gas estimation in production. Set appropriate gas limits for complex transactions.
+
+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.
+
+5. **Order Management**: Store order IDs for later cancellation. Use client order IDs for easier tracking. Implement proper order status monitoring.
+
 ## Resources
 
 - 📚 [Full Documentation](https://docs.decibel.trade) - Complete API and transaction documentation