Liquidity

Liquidity is what a pool trades against. In a public pool anyone can add liquidity and gets shares of the pool, which earn the fees that stay in the pool. In a private pool only the owner adds and removes it. Launch pools don’t take liquidity after creation. See Pools.

All of these are dex_calls. The assets you attach come from your inner balance. What comes back, the assets of removed liquidity and what an addition didn’t use, is sent to your wallet.

The examples on this page add liquidity to pool 221, NEAR/USDT, and remove it, after this setup. Together they’re one script.

near contract call-function as-transaction dex.intear.near storage_deposit \
  json-args '{}' \
  prepaid-gas '30.0 Tgas' attached-deposit '0.01 NEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction dex.intear.near register_assets \
  json-args '{"asset_ids": ["near", "nep141:usdt.tether-token.near"]}' \
  prepaid-gas '30.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction dex.intear.near deposit_near \
  json-args '{}' \
  prepaid-gas '30.0 Tgas' attached-deposit '1.01 NEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

near contract call-function as-transaction usdt.tether-token.near ft_transfer_call \
  json-args '{"receiver_id": "dex.intear.near", "amount": "10000000", "msg": ""}' \
  prepaid-gas '50.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

Caution

Assets sent to your wallet need it to be registered on their token contracts. If a transfer fails, the engine puts the assets in your inner balance, but only if they’re registered for you there. If they’re not, they go back to Plach’s inner balance, and they’re no longer yours. Register the assets of a pool for yourself before you remove liquidity.

Public pools

Register

Before your first addition to a pool, register for its shares with register_liquidity. Its argument is the pool ID, a Borsh u32. Attach NEAR for the storage: Plach uses what it needs and sends the rest to your wallet.

near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/xyk",
    "method": "register_liquidity",
    "args": "3QAAAA==",
    "attached_assets": {"near": "10000000000000000000000"}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

The creator of a public pool is registered already.

Add

add_liquidity takes the pool ID and the least shares you accept:

struct AddLiquidityArgs {
    pool_id: u32,
    min_shares_received: Option<u128>,
}

Attach both assets of the pool. Plach mints shares for the amounts in the pool’s current ratio, limited by the asset you attached less of, takes what that needs of each, and sends the rest to your wallet. So attach a bit more than the ratio needs of both. 3QAAAAA= is pool 221 with no minimum:

near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/xyk",
    "method": "add_liquidity",
    "args": "3QAAAAA=",
    "attached_assets": {
      "near": "1000000000000000000000000",
      "nep141:usdt.tether-token.near": "10000000"
    }
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

Set min_shares_received to fail if the ratio moved before your call, instead of adding liquidity at a worse price.

Your shares

get_pool_shares takes a list of pool IDs and an account, and returns a Borsh Vec<Option<u128>>: the shares in each pool, or None if the account isn’t registered for it.

near contract call-function as-read-only dex.intear.near dex_view \
  json-args '{
    "dex_id": "slimedragon.near/xyk",
    "method": "get_pool_shares",
    "args": "AQAAAN0AAAAKAAAAYWxpY2UubmVhcg=="
  }' \
  network-config mainnet now

Your part of the pool is shares / total_shares of each of its balances. get_pool returns total_shares and the balances.

Remove

struct RemoveLiquidityArgs {
    pool_id: u32,
    /// All of your shares if `None`
    shares_to_remove: Option<u128>,
    /// Fails if you'd get less of either asset
    min_assets_received: Option<(u128, u128)>,
}

Don’t attach anything. Your part of both assets is sent to your wallet. 3QAAAAAA removes all of your liquidity from pool 221, without minimums:

near contract call-function as-transaction dex.intear.near dex_call \
  json-args '{
    "dex_id": "slimedragon.near/xyk",
    "method": "remove_liquidity",
    "args": "3QAAAAAA",
    "attached_assets": {}
  }' \
  prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' \
  sign-as alice.near network-config mainnet sign-with-keychain send

Private pools

The owner of a private pool adds liquidity with add_liquidity too, but there are no shares: all attached assets go into the pool, in any ratio, and min_shares_received must be None. The ratio is the price, so adding unevenly moves it.

To remove, shares_to_remove is the part of the pool to take out, where 1000000000000000000 (10¹⁸) is all of it, and None also means all of it. A locked pool’s liquidity can’t be removed.

Events

Adding and removing liquidity log LiquidityAdded and LiquidityRemoved, with the amounts, the shares, and what the provider owns after.