Leverage Yield

            ┌───────────────────────────────────────────────┐
            │                                               │
            ▼                                               │
   deposit asset ──▶ supply as collateral ──▶ borrow borrowToken
   (e.g. weETH vault) (earns supply APR)       (pays borrow APR)
                                                     │
                                                     ▼
                          re-supply ◀── swap back into asset
                                        (borrowToken → asset)
            │                                               ▲
            └───────────────── repeat until targetLTV ──────┘

netApr = supplyApr + leverageMultiplier × (supplyApr − borrowApr)

netApr = 5% + 5.67 × (5% − 3%) = 5% + 11.33% = 16.33%

const sodax = new Sodax({
  leverageYield: { partnerFee: { address: '0xYourFeeReceiver...', percentage: 100 } }, // 100 bps = 1%
  // ...rest of config
});

const intentResult = await sodax.leverageYield.deposit({
  // ...deposit params
  partnerFee: { address: '0xYourFeeReceiver...', percentage: 100 },
});
// intentResult.value = { params, partnerFee } — spread into vaultSwap() as usual.

// Deposit quote. For a withdraw, swap the two sides: the vault on SONIC_MAINNET is token_src,
// the output token on its chain is token_dst, and amount is the lsoda* shares to burn.
const inputAmount = 1_000_000_000_000_000_000n; // 1 weETH, in the input token's decimals
const quote = await sodax.leverageYield.getQuote({
  token_src: '0x...weETHonArbitrum',                   // spoke token in
  token_src_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
  token_dst: vault.vault,                              // the vault, always on Sonic
  token_dst_blockchain_id: ChainKeys.SONIC_MAINNET,
  amount: inputAmount,
  quote_type: 'exact_input',
  // partnerFee — pass the same value you pass to deposit()/withdraw()/vaultSwap(), or omit on both
});
if (!quote.ok) return;

const slippageBps = 100n; // 1%
const minOutputAmount = (quote.value.quoted_amount * (10_000n - slippageBps)) / 10_000n;

import { ChainKeys } from '@sodax/sdk';

const vault = sodax.leverageYield.getVault('lsodaWEETH');
if (!vault) throw new Error('Unknown vault');
const srcChainKey = ChainKeys.ARBITRUM_MAINNET;

const intentResult = await sodax.leverageYield.deposit({
  vault: vault.vault,
  srcChainKey,
  srcAddress: '0xYourArbitrumEOA...',
  inputToken: '0x...weETHonArbitrum',
  inputAmount, // the amount you quoted, in input-token decimals
  minOutputAmount, // lsoda* (18 dp): the quote minus slippage, from Quoting above
});

if (!intentResult.ok) throw intentResult.error;

// The spoke asset manager pulls `inputToken`, so approve it first — the swap-domain helpers take the payload's params.
const allowance = await sodax.swaps.isAllowanceValid({ params: intentResult.value.params, walletProvider: evmWalletProvider });
if (!allowance.ok) throw allowance.error;
if (!allowance.value) {
  // Pin the chain so the result narrows to an EVM tx hash.
  const approval = await sodax.swaps.approve<typeof srcChainKey, false>({
    params: { ...intentResult.value.params, srcChainKey },
    walletProvider: evmWalletProvider,
  });
  if (!approval.ok) throw approval.error;
  const receipt = await evmWalletProvider.waitForTransactionReceipt(approval.value);
  // Providers report a revert as viem's 'reverted' or the JSON-RPC '0x0'.
  if (receipt.status === 'reverted' || receipt.status === '0x0') throw new Error('Approval reverted');
}

// Spread the payload straight into the vault-swap executor.
const swapResult = await sodax.leverageYield.vaultSwap({
  ...intentResult.value,
  walletProvider: evmWalletProvider,
});

const strategy = await sodax.leverageYield.getApprovalStrategy({ ...intentResult.value, walletProvider: evmWalletProvider });
// 'not-required' | 'atomic-batch' | 'sequential' — label the button before the user clicks

const result = await sodax.leverageYield.vaultSwapWithApproval({ ...intentResult.value, walletProvider: evmWalletProvider });
if (result.ok) console.log(result.value.approvalStrategy, result.value.intentDeliveryInfo.srcTxHash);

const intentResult = await sodax.leverageYield.withdraw({
  vault: vault.vault,
  srcChainKey: ChainKeys.ARBITRUM_MAINNET, // chain the user signs the sendMessage on
  srcAddress: '0xYourArbitrumEOA...',
  dstChainKey: ChainKeys.ARBITRUM_MAINNET, // where the swapped-back token is delivered
  outputToken: '0x...weETHonArbitrum',
  inputAmount: shareBalance, // lsoda* shares (18 dp)
  minOutputAmount: withdrawMinOutputAmount, // from a withdraw quote (vault as token_src) minus slippage, as in Quoting
  // recipient?: defaults to srcAddress
});

if (intentResult.ok) {
  const swapResult = await sodax.leverageYield.vaultSwap({
    ...intentResult.value, // hubWalletSwap: true is already set on the payload
    walletProvider: evmWalletProvider,
  });
}

// Backend 2-step is the default (client-side fallback still applies).
const sodax = new Sodax();

// Opt out — fully client-side relay + notify-solver.
const sodaxClientSide = new Sodax({ leverageYield: { useBackendSubmitTx: false } });

// Key the backend leg for one vault swap, overriding the instance `apiKey`. Server-side only.
const result = await sodax.leverageYield.vaultSwap({
  params,
  walletProvider,
  extras: { apiKey: 'partner-key' },
});

const ok = await sodax.leverageYield.isAllowanceValid({
  vault: vault.vault,
  amount: 1_000_000_000_000_000_000n,
  owner: '0xHubWallet...',
});

if (ok.ok && !ok.value) {
  await sodax.leverageYield.approve({
    vault: vault.vault,
    amount: 1_000_000_000_000_000_000n,
    walletProvider: evmWalletProvider,
  });
}

const result = await sodax.leverageYield.getDetailedStatus({
  srcChainKey: ChainKeys.ARBITRUM_MAINNET,
  srcTxHash: vaultSwapResponse.intentDeliveryInfo.srcTxHash,
});

if (result.ok) {
  if (result.value.source === 'backend') {
    // `data` is the SubmitTxStatusDataV2 from sodax.api.leverageYield.getSubmitTxStatus
    console.log(result.value.data.status); // pending … posted_execution | solved
  } else {
    // `data` is the SolverIntentStatusResponse — the vault intent IS a solver intent.
    // A failed or abandoned backend record routes here, so failure is the solver's FAILED code.
    console.log(result.value.data.status, result.value.dstTxHash);
  }
}

type DetailedLeverageYieldStatus =
  | { source: 'backend'; data: SubmitTxStatusDataV2 }
  | { source: 'solver'; dstTxHash: Hex; data: SolverIntentStatusResponse };

import { summarizeSwapStatus } from '@sodax/sdk';

if (result.ok) {
  const { state, hubTxHash, fillTxHash } = summarizeSwapStatus(result.value);
  // state: 'pending' | 'solved' | 'failed'. fillTxHash may be absent even when solved.
}

type LeverageYieldVault = {
  name: string;        // lookup key — the lsoda* share-token symbol (e.g. 'lsodaWEETH')
  vault: Address;      // deployed vault proxy on Sonic — also the lsoda* token address
  asset: Address;      // underlying Sodax vault token (e.g. SodaTokens.sodaWEETH, symbol weETH)
  borrowToken: Address; // token borrowed against asset (e.g. sodaETH)
};

type LeverageYieldApr = {
  supplyAprRay: bigint;          // AAVE supply rate of asset, in RAY (1e27)
  borrowAprRay: bigint;          // AAVE variable borrow rate of borrowToken, in RAY
  targetLtvBps: bigint;          // vault targetLTV(), in basis points
  leverageMultiplierWad: bigint; // targetLTV / (1 - targetLTV), in WAD (1e18): borrowed multiple; exposure = 1 + this
  netAprRay: bigint;             // net APR at targetLTV, in RAY — can be negative
};

type LeverageYieldPosition = {
  collateral: bigint;   // collateral supplied to the pool — vault-asset units (18 decimals)
  debt: bigint;         // outstanding borrowToken debt — vault-asset units (18 decimals)
  ltv: bigint;          // current loan-to-value in basis points (out of 10_000; 8_500 = 85%)
  healthFactor: bigint; // AAVE health factor in WAD (1e18); below 1e18 implies liquidation risk, type(uint256).max = no debt
  idleAsset: bigint;    // asset held by the vault but not yet supplied — vault-asset units (18 decimals)
};

const result = await sodax.leverageYield.deposit({ /* ... */ });

if (!result.ok) {
  switch (result.error.code) {
    case 'VALIDATION_FAILED':
      // Bad input — error.context.field names the offending parameter.
      console.error('Bad input:', result.error.message, result.error.context?.field);
      break;
    case 'INTENT_CREATION_FAILED':
      // Building the swap params failed (e.g. hub-wallet resolution). cause has the original.
      console.error('Intent creation failed:', result.error.cause);
      break;
    case 'LOOKUP_FAILED':
      // An on-chain read failed — e.g. the default-deadline hub-block read (method='resolveDeadline').
      console.error('Lookup failed:', result.error.context?.method, result.error.cause);
      break;
    case 'UNKNOWN':
      console.error('Unexpected:', result.error.cause);
      break;
  }
}

const sodax = new Sodax({ leverageYield: { positionFactory: '0x…' } });

const result = await sodax.leverageYield.openLeveragePosition({
  side: 'collateral',                // 'debt' funds with the debt token instead
  params: { srcChainKey, srcAddress, token, amount, eModeCategory, borrowToken, borrowAmount, minCollateralOut },
  walletProvider,
});
if (!result.ok) throw result.error;
// Resolving means the intent is LIVE, not that the position is open.
if (!result.value.notified) warn(result.value.notifyError);

import { sizeLeverageBorrow, projectLeverageLeg, type LeverageLegRequest } from '@sodax/sdk';

const request: LeverageLegRequest = {
  side: 'collateral',            // 'debt' when funding with the debt token instead
  deposit: parseUnits('100', 18),
  depositDecimals: 18,
  collateralPriceUsd: Number(collateralReserve.priceInUSD),
  borrowPriceUsd: Number(borrowReserve.priceInUSD),
  borrowDecimals: borrowReserve.decimals,
  leverage: 3,
};

// 1. Oracle-sized, because there is nothing else yet. Quote `intentInput`, not `borrowAmount`:
//    on a debt-side open the user's contribution goes to the solver too. Use
//    `getPositionLegQuote` rather than `getQuote`: it names the hub reserves the intent swaps and
//    quotes gross, which are the two details a hand-rolled call gets wrong.
const { borrowAmount, intentInput } = sizeLeverageBorrow(request);
const leg = await sodax.leverageYield.getPositionLegQuote({
  inputHubToken: borrowReserve.underlyingAsset,   // the hub RESERVE address, not the reserve object
  outputHubToken: collateralReserve.underlyingAsset,
  amount: intentInput,
});
if (!leg.ok) throw leg.error;
const quoted = leg.value.quotedAmount;

// 2. Now the honest numbers, from the quote.
const p = projectLeverageLeg(request, { quotedCollateral: quoted, collateralDecimals: 18 }, riskParams, 1);
if (p.exceedsMaxLtv) throw new Error(`too high at this price; max is ~${p.usableMaxLeverage.toFixed(2)}x`);

// `openLeveragePosition`, not `openPosition`: the latter posts the intent and leaves reporting it
// to you, and an unreported intent expires unfilled.
const opened = await sodax.leverageYield.openLeveragePosition({
  params: { ...funding, borrowToken, borrowAmount, minCollateralOut: p.minCollateralOut },
  walletProvider,
});
if (!opened.ok) throw opened.error;
if (!opened.value.notified) warn(opened.value.notifyError);