Deposit Service

import {
  detectUsdcArrival,
  detectUsdcArrivalFromSnapshot,
  snapshotUsdcBalance,
  checkUsdcBalance,
  UsdcArrivalTimeoutError,
  isUsdcArrivalTimeoutError,
  ARRIVAL_DETECTION_TIMEOUT_MS,
  ARRIVAL_POLL_INTERVAL_MS,
} from '@mina-bridge/sdk/services/deposit';

async function detectUsdcArrival(
  walletAddress: string,
  options?: DetectionOptions
): Promise<UsdcArrivalResult>

const arrival = await detectUsdcArrival('0x...', {
  timeout: 300000, // 5 minutes
  onPoll: (attempt, balance) => {
    console.log(`Poll ${attempt}: Balance = ${balance}`);
  },
});

if (arrival.detected) {
  console.log(`USDC arrived: ${arrival.amountFormatted} USDC`);
  // Proceed to deposit
}

async function snapshotUsdcBalance(walletAddress: string): Promise<string>

// Before bridge
const preBalance = await snapshotUsdcBalance('0x...');

// Execute bridge...
await execute({ quote, signer });

// Detect arrival from snapshot
const arrival = await detectUsdcArrivalFromSnapshot(
  '0x...',
  preBalance,
  { expectedAmount: quote.toAmount }
);

async function detectUsdcArrivalFromSnapshot(
  walletAddress: string,
  previousBalance: string,
  options?: DetectionOptions
): Promise<UsdcArrivalResult>

async function checkUsdcBalance(walletAddress: string): Promise<{
  balance: string;
  balanceFormatted: string;
  chainId: number;
  tokenAddress: string;
}>

const { balance, balanceFormatted } = await checkUsdcBalance('0x...');
console.log(`HyperEVM USDC: ${balanceFormatted}`);

import {
  executeDeposit,
  executeDepositFor,
  validateDepositRequirements,
  approveUsdcForDeposit,
  checkDepositAllowance,
  // Constants
  CORE_DEPOSIT_WALLET_ADDRESS,
  MINIMUM_DEPOSIT_AMOUNT,
  DestinationDex,
  CORE_DEPOSIT_WALLET_ABI,
  ERC20_ABI,
  // Errors
  MinimumDepositError,
  InsufficientGasError,
  DepositTransactionError,
  InvalidDepositAddressError,
  isMinimumDepositError,
  isInsufficientGasError,
  isDepositTransactionError,
  isInvalidDepositAddressError,
} from '@mina-bridge/sdk/services/deposit';

async function executeDeposit(
  signer: DepositSigner,
  options: DepositOptions
): Promise<DepositResult>

interface DepositSigner {
  sendTransaction: (request: {
    to: string;
    data: string;
    value?: string;
    gas?: string;
    chainId: number;
  }) => Promise<string>;
  getAddress: () => Promise<string>;
  waitForTransactionReceipt?: (hash: string) => Promise<{
    status: 'success' | 'reverted';
    blockNumber: bigint;
    gasUsed: bigint;
  }>;
}

import { executeDeposit, DestinationDex } from '@mina-bridge/sdk';

const result = await executeDeposit(walletSigner, {
  amount: '10000000', // 10 USDC (6 decimals)
  walletAddress: '0x...',
  destinationDex: DestinationDex.PERPS, // Trading account
  onStatusChange: (status) => {
    console.log(`Status: ${status}`);
    // checking_balance -> checking_allowance -> approving ->
    // approval_pending -> approval_confirmed -> depositing ->
    // deposit_pending -> deposit_confirmed -> completed
  },
  onDepositSubmitted: (txHash) => {
    console.log(`Deposit submitted: ${txHash}`);
  },
  infiniteApproval: true, // Save gas on future deposits
});

if (result.success) {
  console.log(`Deposited ${result.amountFormatted} USDC`);
  console.log(`TxHash: ${result.depositTxHash}`);
}

async function executeDepositFor(
  signer: DepositSigner,
  recipientAddress: string,
  options: DepositOptions
): Promise<DepositResult>

// Deposit to a different trading account
const result = await executeDepositFor(
  walletSigner,
  '0xRecipientAddress...',
  {
    amount: '50000000', // 50 USDC
    walletAddress: '0xMyWallet...',
    destinationDex: DestinationDex.PERPS,
  }
);

async function validateDepositRequirements(
  walletAddress: string,
  amount: string
): Promise<DepositValidation>

const validation = await validateDepositRequirements(
  '0x...',
  '10000000' // 10 USDC
);

if (!validation.valid) {
  console.error('Cannot deposit:', validation.error);
  return;
}

if (validation.needsApproval) {
  console.log('Approval will be required');
}

console.log(`USDC Balance: ${validation.usdcBalanceFormatted}`);
console.log(`Gas Balance: ${validation.gasBalance}`);

async function approveUsdcForDeposit(
  signer: DepositSigner,
  amount: string,
  onSubmitted?: (txHash: string) => void
): Promise<{
  txHash: string;
  receipt: {
    status: 'success' | 'reverted';
    blockNumber: bigint;
    gasUsed: bigint;
  };
}>

async function checkDepositAllowance(walletAddress: string): Promise<{
  allowance: string;
  allowanceFormatted: string;
}>

import {
  monitorL1Confirmation,
  waitForL1Confirmation,
  getHyperliquidBalance,
  getL1TradingBalance,
  checkHyperliquidAccountExists,
  createBridgeCompleteSummary,
  // Constants
  HYPERLIQUID_INFO_API,
  L1_CONFIRMATION_TIMEOUT_MS,
  L1_HARD_MAX_TIMEOUT_MS,
  L1_POLL_INTERVAL_MS,
  L1_USDC_DECIMALS,
  // Errors
  L1MonitorCancelledError,
  InvalidL1AddressError,
  isL1MonitorCancelledError,
  isInvalidL1AddressError,
} from '@mina-bridge/sdk/services/deposit';

function monitorL1Confirmation(
  walletAddress: string,
  expectedAmount: string,
  hyperEvmTxHash: string,
  options?: L1MonitorOptions
): {
  result: Promise<L1ConfirmationResult>;
  controller: L1MonitorController;
}

interface L1MonitorController {
  cancel: () => void;
  extendTimeout: (additionalMs: number) => void;
  getStatus: () => {
    elapsed: number;
    timeout: number;
    isRunning: boolean;
    cancelled: boolean;
    completed: boolean;
  };
}

// Start monitoring with controller
const { result, controller } = monitorL1Confirmation(
  '0x...',
  '10000000', // Expected 10 USDC
  depositResult.depositTxHash,
  {
    timeout: 120000, // 2 minutes
    onProgress: (p) => {
      console.log(`Checking L1... ${p.elapsed / 1000}s elapsed`);
      console.log(`Balance: ${p.currentBalance}`);
    },
    onTimeoutWarning: (w) => {
      console.warn('Timeout warning - still monitoring');
    },
  }
);

// Can extend timeout if needed
setTimeout(() => {
  const status = controller.getStatus();
  if (status.isRunning && status.elapsed > 60000) {
    console.log('Extending timeout by 1 minute...');
    controller.extendTimeout(60000);
  }
}, 60000);

// Await the result
try {
  const confirmation = await result;
  console.log(`Confirmed: ${confirmation.amountFormatted} USDC`);
  console.log(`Final balance: ${confirmation.finalBalanceFormatted}`);
  console.log(`Time: ${confirmation.confirmationTime}ms`);
} catch (error) {
  if (isL1MonitorCancelledError(error)) {
    console.log('Monitoring cancelled or timed out');
  }
}

async function waitForL1Confirmation(
  walletAddress: string,
  expectedAmount: string,
  hyperEvmTxHash: string,
  options?: L1MonitorOptions
): Promise<L1ConfirmationResult>

const confirmation = await waitForL1Confirmation(
  '0x...',
  '10000000',
  depositResult.depositTxHash
);

console.log(`Deposit confirmed: ${confirmation.amountFormatted} USDC`);

async function getHyperliquidBalance(walletAddress: string): Promise<string>

const balance = await getHyperliquidBalance('0x...');
console.log(`L1 Balance: ${Number(balance) / 1e6} USD`);

async function getL1TradingBalance(walletAddress: string): Promise<{
  balance: string;
  balanceFormatted: string;
  chainId: number;
}>

const { balanceFormatted, chainId } = await getL1TradingBalance('0x...');
console.log(`Hyperliquid (${chainId}) Balance: ${balanceFormatted} USD`);

async function checkHyperliquidAccountExists(walletAddress: string): Promise<boolean>

function createBridgeCompleteSummary(params: {
  sourceChainId: number;
  sourceChainName: string;
  sourceTxHash: string;
  bridgeSteps: CompletedStep[];
  bridgeStartTime: number;
  depositResult: DepositResult;
  depositStartTime: number;
  l1MonitorStartTime?: number;
  l1Confirmation: L1ConfirmationResult;
  inputAmount: string;
  totalFeesUsd: number;
}): BridgeCompleteSummary

const DestinationDex = {
  PERPS: 0,           // Trading account (perps)
  SPOT: 4294967295,   // Spot DEX (uint32.max)
} as const;

import {
  detectUsdcArrival,
  executeDeposit,
  monitorL1Confirmation,
  DestinationDex,
} from '@mina-bridge/sdk';

async function bridgeAndDeposit(
  quote: Quote,
  signer: TransactionSigner,
  walletAddress: string
) {
  // 1. Execute bridge
  console.log('Starting bridge...');
  const bridgeResult = await execute({ quote, signer });

  if (bridgeResult.status !== 'completed') {
    throw new Error('Bridge failed');
  }

  // 2. Detect USDC arrival on HyperEVM
  console.log('Waiting for USDC arrival on HyperEVM...');
  const arrival = await detectUsdcArrival(walletAddress, {
    expectedAmount: quote.toAmount,
    onPoll: (attempt) => console.log(`Checking... (attempt ${attempt})`),
  });

  console.log(`USDC arrived: ${arrival.amountFormatted}`);

  // 3. Execute deposit to Hyperliquid L1
  console.log('Depositing to Hyperliquid L1...');
  const depositResult = await executeDeposit(signer, {
    amount: arrival.amount,
    walletAddress,
    destinationDex: DestinationDex.PERPS,
    onStatusChange: (status) => console.log(`Deposit: ${status}`),
  });

  // 4. Monitor L1 confirmation
  console.log('Waiting for L1 confirmation...');
  const { result, controller } = monitorL1Confirmation(
    walletAddress,
    arrival.amount,
    depositResult.depositTxHash,
    { onProgress: (p) => console.log(`L1 check... ${p.elapsed / 1000}s`) }
  );

  const l1Confirmation = await result;

  console.log('\n=== Bridge Complete ===');
  console.log(`Input: ${quote.fromAmount} USDC`);
  console.log(`Deposited: ${l1Confirmation.amountFormatted} USDC`);
  console.log(`Final L1 Balance: ${l1Confirmation.finalBalanceFormatted}`);
  console.log(`Total Time: ${l1Confirmation.confirmationTime}ms`);

  return { bridgeResult, depositResult, l1Confirmation };
}