Developer reference

Abyss Vaults and ATokens

You can find the contracts repository here https://github.com/abyss-protocol/abyss-vaults.git

Table of Contents

• Overview

• Architecture

• Core Components

  • Vault Registry

  • Vault

    • Vault Supply

    • Vault Withdrawal

    • Vault Incentives

Overview

Abyss vaults allow depositors to earn interest on their assets by lending liquidity to DeepBook margin traders, while holding their share of the vault in a fungible way. Users deposit supported assets, receive yield-bearing ATokens that track their proportional claim, and benefit from automated compounding of incentives. Users can then use their ATokens freely across the DeFi ecosystem.

Architecture

Core Components

Vault Registry

Manages vault registration, package versioning, and vault-specific permissions. Enforces one vault per underlying asset type. Enables admins to enable or disable a package version. Verifies the validity of VaultManagerCap and IncentiveManagerCap.

One can retrieve the vault identifier based on the underlying asset type using the public function:

public fun vault_id<Asset>(registry: &VaultRegistry): ID

Vault

The Abyss Vault manages core user operations. It handles user deposits and withdrawals, issues ATokens, synchronizes with the underlying margin pool, and manages incentive compounding.

Vault Supply

public fun supply<Asset, AToken>(
    vault: &mut Vault<Asset, AToken>,
    margin_pool: &mut MarginPool<Asset>,
    vault_registry: &VaultRegistry,
    margin_registry: &MarginRegistry,
    supply: Coin<Asset>,
    abyss_supplier_cap: &AbyssSupplierCap,
    referral: Option<ID>,
    clock: &Clock,
    ctx: &mut TxContext,
    ): Coin<AToken>

The vault supply takes assets and mints the corresponding amount of ATokens, representing shares in the total value of the vault. Yield is redistributed proportionally to the number of shares held. Integrators of Abyss vaults can set the referral parameter to their SupplyReferral object ID to earn referral fees.

Vault Withdrawal

public fun withdraw<Asset, AToken>(
    vault: &mut Vault<Asset, AToken>,
    margin_pool: &mut MarginPool<Asset>,
    vault_registry: &VaultRegistry,
    margin_registry: &MarginRegistry,
    withdraw: Coin<AToken>,
    abyss_supplier_cap: &AbyssSupplierCap,
    clock: &Clock,
    ctx: &mut TxContext,
): Coin<Asset>

The vault withdrawal burns the given amount of ATokens and returns the corresponding amount of assets to the user. Withdrawals honor a first-in, first-out accounting model—if the vault is mid-cycle on incentive compounding, the contract checkpoints earnings before transferring funds to guarantee everyone receives their share.

Package Addresses

Mainnet

Package

Name	Version	Chain	Address
Abyss Vaults	1	Sui Mainnet	0x90a75f641859f4d77a4349d67e518e1dd9ecb4fac079e220fa46b7a7f164e0a5

Objects

Name	Version	Chain	Object ID
Vault Registry	1	Sui Mainnet	0xfac1800074e8ed8eb2baf1e631e8199ccce6b0f6bfd50b5143e1ff47c438aecf
Abyss Supplier Cap	1	Sui Mainnet	0x3d0faab3953525d243275b39cbed465cb310fe2d4dd2c15428b8f7cf5962c2c0

Vaults

Asset	Vault ID	Margin Pool ID
SUI	0x670c12c8ea3981be65b8b11915c2ba1832b4ebde160b03cd7790021920a8ce68	0x53041c6f86c4782aabbfc1d4fe234a6d37160310c7ee740c915f0a01b7127344
DEEP	0xec54bde40cf2261e0c5d9c545f51c67a9ae5a8add9969c7e4cdfe1d15d4ad92e	0x1d723c5cd113296868b55208f2ab5a905184950dd59c48eb7345607d6b5e6af7
WAL	0x09b367346a0fc3709e32495e8d522093746ddd294806beff7e841c9414281456	0x38decd3dbb62bd4723144349bf57bc403b393aee86a51596846a824a1e0c2c01
USDC	0x86cd17116a5c1bc95c25296a901eb5ea91531cb8ba59d01f64ee2018a14d6fa5	0xba473d9ae278f10af75c50a8fa341e9c6a1c087dc91a3f23e8048baf67d0754f

ATokens

Asset	Type	Icon URL
aSUI	0x90a75f641859f4d77a4349d67e518e1dd9ecb4fac079e220fa46b7a7f164e0a5::abyss_vault::AToken<0x2::sui::SUI>	https://d3cny4im7ppv5.cloudfront.net/aSUI.svg
DBUSDC	0x90a75f641859f4d77a4349d67e518e1dd9ecb4fac079e220fa46b7a7f164e0a5::abyss_vault::AToken<0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC>	https://d3cny4im7ppv5.cloudfront.net/aUSDC.svg
aDEEP	0x90a75f641859f4d77a4349d67e518e1dd9ecb4fac079e220fa46b7a7f164e0a5::abyss_vault::AToken<0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP>	https://d3cny4im7ppv5.cloudfront.net/aDEEP.svg
aWAL	0x90a75f641859f4d77a4349d67e518e1dd9ecb4fac079e220fa46b7a7f164e0a5::abyss_vault::AToken<0x356a26eb9e012a68958082340d4c4116e7f55615cf27affcff209cf0ae544f59::wal::WAL>	https://d3cny4im7ppv5.cloudfront.net/aWAL.svg

Typescript reference

// ============================================================================
// Transaction Building Functions
// ============================================================================

/**
 * Build deposit transaction
 *
 * @param params - Deposit parameters
 * @param userAddress - User's wallet address
 * @param env - Environment (mainnet or testnet)
 * @returns Transaction object ready to be signed
 */
export function buildDepositTransaction(
  params: DepositParams,
  userAddress: string,
  env: Environment = "mainnet",
  coinIds?: string[],
): Transaction {
  const packageId = getVaultPackageId(env);
  const vaultRegistryId = getVaultRegistryId(env);
  const marginRegistryId = getMarginRegistryId(env);
  const supplierCapId = getSupplierCapId(env);

  const tx = new Transaction();

  let depositCoin;

  // Check if this is a SUI vault or another asset
  const isSuiVault = params.assetType === "0x2::sui::SUI";

  if (isSuiVault) {
    // For SUI vaults, split from gas
    const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(params.amount)]);
    depositCoin = coin;
  } else {
    // For non-SUI vaults, we need to use provided coin IDs
    if (!coinIds || coinIds.length === 0) {
      throw new Error("Coin IDs required for non-SUI vault deposits");
    }

    // Merge all coins if multiple
    let primaryCoin;
    if (coinIds.length === 1) {
      primaryCoin = tx.object(coinIds[0]);
    } else {
      const [firstCoin, ...restCoins] = coinIds;
      tx.mergeCoins(
        tx.object(firstCoin),
        restCoins.map((id) => tx.object(id)),
      );
      primaryCoin = tx.object(firstCoin);
    }

    // Split the exact amount needed
    const [coin] = tx.splitCoins(primaryCoin, [tx.pure.u64(params.amount)]);
    depositCoin = coin;
  }

  
  // Determine the appropriate referral address based on asset type
  let optionAddress: string;
  if (params.assetType.includes("::deep::")) {
    // DEEP token address
    optionAddress = "0x434c4d10328fe29206ae4c7a42869b07a4eb4619a48b8e502604287417fea220";
  } else if (params.assetType.includes("::wal::")) {
    // WAL token address
    optionAddress = "0xb29d0f48cacbee7be4dab1524a0f995f41f33bd5fdb05492f69af85738dc6c56";
  } else if (params.assetType.includes("::usdc::")) {
    // USDC token address
    optionAddress = "0xba436b3f0e57600e9318c2e03c51b940612d8b0d4df18ad9f31c203f95cad122";
  } else if (params.assetType === "0x2::sui::SUI") {
    // SUI token address
    optionAddress = "0x695b391423801750827e0b99792a7cd5e41bee3d90b2af03fc99197938c6c98d";
  } else {
    throw new Error("Unsupported asset type for deposit: " + params.assetType);
  }

  // Call deposit function
  const [atokenCoin] = tx.moveCall({
    target: `${packageId}::abyss_vault::supply`,
    arguments: [
      tx.object(params.vaultId),
      tx.object(params.marginPoolId),
      tx.object(vaultRegistryId),
      tx.object(marginRegistryId),
      depositCoin,
      tx.object(supplierCapId),
      tx.pure.option("id", optionAddress),
      tx.object(CLOCK_ID),
    ],
    typeArguments: [params.assetType, params.atokenType],
  });

  // Transfer ATokens to user
  tx.transferObjects([atokenCoin], userAddress);

  return tx;
}

/**
 * Build withdraw transaction
 *
 * @param params - Withdraw parameters
 * @param userAddress - User's wallet address
 * @param env - Environment (mainnet or testnet)
 * @returns Transaction object ready to be signed
 */
export function buildWithdrawTransaction(
  params: WithdrawParams,
  userAddress: string,
  env: Environment = "mainnet",
): Transaction {
  const packageId = getVaultPackageId(env);
  const vaultRegistryId = getVaultRegistryId(env);
  const marginRegistryId = getMarginRegistryId(env);
  const supplierCapId = getSupplierCapId(env);

  const tx = new Transaction();

  // If multiple AToken coins, merge them first
  let atokenCoin;
  if (params.atokenCoinIds.length === 1) {
    atokenCoin = tx.object(params.atokenCoinIds[0]);
  } else if (params.atokenCoinIds.length > 1) {
    // Merge all coins into the first one
    const [firstCoin, ...restCoins] = params.atokenCoinIds;
    tx.mergeCoins(
      tx.object(firstCoin),
      restCoins.map((id) => tx.object(id)),
    );
    atokenCoin = tx.object(firstCoin);
  } else {
    throw new Error("No AToken coins provided for withdrawal");
  }

  // Split the exact amount to withdraw
  const [withdrawCoin] = tx.splitCoins(atokenCoin, [
    tx.pure.u64(params.atokenAmount),
  ]);

  // Call withdraw function
  const [assetCoin] = tx.moveCall({
    target: `${packageId}::abyss_vault::withdraw`,
    arguments: [
      tx.object(params.vaultId),
      tx.object(params.marginPoolId),
      tx.object(vaultRegistryId),
      tx.object(marginRegistryId),
      withdrawCoin,
      tx.object(supplierCapId),
      tx.object(CLOCK_ID),
    ],
    typeArguments: [params.assetType, params.atokenType],
  });

  // Transfer withdrawn assets to user
  tx.transferObjects([assetCoin], userAddress);

  return tx;
}

Resources

• DeepBook Margin Documentation

• Abyss Vaults Move Registry Reference