Anchor Earn SDK

Last updated 3 years ago

Anchor Earn is a JavaScript SDK that specializes for integrations that are wishing to leverage the deposit functionality of Anchor.

Anchor Earn only covers the savings-related operations of Anchor. For a SDK with full functional coverage (e.g. minting bLuna, borrowing UST), Anchor.js is recommended.

Anchor Earn is designed with interchain access in mind. Further releases of Anchor Earn are to enable integrations for interchain deposits, opening up savings for applications outside of the Terra blockchain. With the use of EthAnchor, BscAnchor, SolAnchor, etc., Anchor Earn is to be further expanded to enable savings regardless of blockchain or the type of stablecoin.

A complete list of supported blockchains and stablecoins are outlined in the appendix section.

For those interested in reading the code, please refer to the Anchor Earn repository.

Installation

Anchor Earn requires NPM and Node.js 12 or above for its proper usage.

Anchor Earn is available as a package on NPM. Add @anchor-protocol/anchor-earn to your JavaScript project's package.json as dependencies using preferred package manager:

npm install -S @anchor-protocol/anchor-earn

yarn add @anchor-protocol/anchor-earn

Initialization

Initializing Anchor Earn

`AnchorEarn({chain, network, privateKey?, MnemonicKey?, address?})`

AnchorEarn creates an instance of the AnchorEarn object, used as the entry point to the Anchor Earn SDK.

A blockchain account is required when calling this function. Register the account's private key or mnemonics from which transactions will be signed and broadcasted. If you do not have a pre-created blockchain account, a new account can be created using the Account instance.

While Anchor Earn by default handles transaction signing and broadcasting, these operations can be handed off to a callback function that connects with external key-signing solutions (e.g. Terra Station Extension, Ledger Hardware Wallet, Custodian APIs). For this case, the AnchorEarn instance should be created by the pre-created account's address.

Method Parameters

Parameter / Type / Optionality / Description

Blockchain to interact from.

For Anchor Earn v1.0, only CHAINS.TERRA (Terra blockchain) is supported.

Network to interact in.

privateKey (Buffer | any) Optional

Account private key.

mnemonic (string | any) Optional

Account mnemonics.

address (string) Optional

Account address.

Example

const anchorEarn = new AnchorEarn({
  chain: CHAINS.TERRA,
  network: NETWORKS.BOMBAY_12,
  mnemonic: '...',
});

Creating a New Blockchain Account

`Account(chain)`

Creating an instance of the Account object generates a new blockchain account.

Tokens for testnet environments (e.g. Bombay) can be acquired using faucets, outlined in the appendix section.

Method Parameters

Parameter / Type / Optionality / Description

Blockchain to generate account on.

Example

// generate a new Terra account 
const account = new Account(CHAINS.TERRA);

The Account instance contains the information for the newly created account.

export class Account {
  accAddress: AccAddress;
  publicKey: string;
  privateKey: Buffer;
  mnemonic: string;
}

privateKey and mnemonic constitute as your access key to your account, including the control of your assets.

PLEASE RECORD AND STORE THEM IN A SAFE PLACE AND NEVER SHARE EXTERNALLY.

Attributes

Attribute / Type / Description

accAddress (AccAddress)

Address of account.

publicKey (string)

Public key of account.

privateKey (Buffer)

Private key of account.

mnemonic (string)

Mnemonics of account.

Generating an Account with Mnemonics

`MnemonicKey({mnemonic})`

An account can also be generated using existing mnemonics. The MnemonicKey object is borrowed from Terra.js, allowing integrators to access it without any dependencies on Terra.js.

Method Parameter

Parameter / Type / Optionality / Description

mnemonic (string) Required

Mnemonics of account.

import { Wallet, MnemonicKey } from '@anchor-protocol/anchor-earn';
const account = new MnemonicKey({
  mnemonic: '...',
});

Usage

For compatibility across tokens with various decimals, Anchor Earn unifies all currency amounts to use the decimal representation. As an example, a value of 10.1 in the amount field will lead to the utilization of 10.1 currency tokens.

Deposit Stablecoins to Anchor

`anchorEarn.deposit({currency, amount})`

This method deposits the specified amount of stablecoins to Anchor.

Method Parameters

Parameter / Type / Optionality / Description

Currency of stablecoin to deposit.

amount (string) Required

Amount of stablecoins to deposit.

Callback function provided by the integrator that creates, signs a transaction encoding the deposit request and returns the signed transaction to be broadcasted by Anchor Earn.

CustomBroadcaster (callback function => string) Optional

Callback function provided by the integrator that creates, signs and broadcasts a transaction that encodes the deposit request. Expects the tx hash of the broadcasted transaction in string format.

Loggable (callback function) Optional

Callback function that logs transaction requests.

Returns

anchorEarn.deposit will return a Promise which resolves with either a OperationError or TxOutput object which implements the Output interface.

Example

const deposit = await anchorEarn.deposit({
  currency: DENOMS.UST,
  amount: '12.345', // 12.345 UST or 12345000 uusd
});

Withdraw Stablecoins from Anchor

`anchorEarn.withdraw({currency, amount})`

This method withdraws the specified amount of stablecoins (or their aTerra counterpart) from Anchor.

Note that the actual amount of stablecoins withdrawn will be smaller due to transfer fees (tax) enforced by the Terra blockchain.

Method Parameters

Parameter / Type / Optionality / Description

Currency of stablecoin to withdraw or their aTerra counterpart.

amount (string) Required

Amount of stablecoins (or their aTerra counterpart) to withdraw.

Callback function provided by the integrator that creates, signs a transaction encoding the withdraw request and returns the signed transaction to be broadcasted by Anchor Earn.

CustomBroadcaster (callback function => string) Optional

Callback function provided by the integrator that creates, signs and broadcasts a transaction that encodes the withdraw request.

Expects the tx hash of the broadcasted transaction in string format.

Loggable (callback function) Optional

Callback function that logs transaction requests.

Returns

anchorEarn.withdraw will return a Promise which resolves with either a OperationError or TxOutput object which implements the Output interface.

Example

const withdraw = await anchorEarn.withdraw({
  currency: DENOMS.UST,
  amount: '12.345', // 12.345 UST or 12345000 uusd
});

Send Tokens

`anchorEarn.send({currency, recipient, amount})`

Use anchorEarn.send to send tokens (stablecoins or their aTerra counterpart) to a different account.

Method Parameters

Parameter / Type / Optionality / Description

Currency of token (stablecoins or their aTerra counterpart) to send.

recipient (string) Required

Recipient address to receive sent tokens.

amount (string) Required

Amount of tokens (stablecoins or their aTerra counterpart) to send.

CustomSigner (callback function => StdTx) Optional

Callback function provided by the integrator that creates, signs a transaction encoding the send request and returns the signed transaction to be broadcasted by Anchor Earn.

CustomBroadcaster (callback function => string) Optional

Callback function provided by the integrator that creates, signs and broadcasts a transaction that encodes the send request.

Expects the tx hash of the broadcasted transaction in string format.

Loggable (callback function) Optional

Callback function that logs transaction requests.

Returns

anchorEarn.send will return a Promise which resolves with either a OperationError or TxOutput object which implements the Output interface.

Example

const sendUst = await anchorEarn.send({
  currency: DENOMS.UST, 
  recipient: 'terra1...', 
  amount: '12.345', // 12.345 UST or 12345000 uusd
});

Retrieve Balance Information

`anchorEarn.balance({currencies})`

This method retrieves balance information for the specified stablecoins.

Method Parameters

Parameters / Type / Optionality / Description

List of currencies to retrieve balances.

Returns

anchorEarn.balance will return a Promise which resolves with a BalanceOutput object.

Example

const balanceInfo = await anchorEarn.balance({
  currencies: [
    DENOMS.UST
  ],
});

Retrieve Market Information

`anchorEarn.market({currencies})`

This method retrieves market information for the specified stablecoins.

Method Parameters

Parameter / Type / Optionality / Description

List of stablecoins to retrieve information about their markets.

Returns

anchorEarn.market will return a Promise which resolves with a MarketOutput object.

Example

const marketInfo = await anchorEarn.market({
  currencies: [
    DENOMS.UST
  ],
});

Resources

CHAINS

The CHAINS enumerated type specifies blockchains that are supported by Anchor Earn.

export enum CHAINS {
  TERRA = 'terra',
}

Anchor Earn currently supports the following blockchains:

Enum Member

Blockchain Name

CHAINS.TERRA

NETWORKS

The NETWORKS enumerated type specifies the network type to be used.

export enum NETWORKS {
  COLUMBUS_5,
  BOMBAY_12,
}

Anchor Earn supports mainnet and testnet networks with the below chain IDs:

Mainnet

Enum Member

Chain ID

Network Name

COLUMBUS_5

columbus-5

Columbus 5

Testnet

Enum Member

Chain ID

Network Name

BOMBAY_12

bombay-12

Bombay

DENOMS

Specifies stablecoin currency denominations.

export enum DENOMS {
  UST = 'uusd',
  AUST = 'uaust',
}

Anchor Earn supports functionalities for the below stablecoin denominations:

Mainnet

Denomination

Code

Decimals

Contract Address

UST

uusd

Native Token

aUST

uaust

Testnet

Denomination

Code

Decimals

Contract Address

UST

uusd

Native Token

aUST

uaust

OperationError

Represents an error that was returned by a request.

export interface OperationError {
  chain: string;
  network: string;
  status: STATUS;
  type: TxType;
  error_msg: string;
}

Attributes

Attribute / Type / Description

Blockchain from which the request was made.

Network from which the request was made.

Request status. Should display UNSUCCESSFUL as the request encountered an error.

Request type. Can be either of:

deposit: request is a transaction that deposits stablecoins to Anchor.
withdraw: request is a transaction that withdraws stablecoins from Anchor.
send: request is a transaction that sends tokens to a different account.

error_msg (string)

Human-readable sentence describing the error.

Output

Represents information for a request made via Anchor Earn.

export interface Output {
  chain: string;
  network: string;
  status: STATUS;
  type: TxType;
  currency: string;
  amount: string;
  txDetails: TxDetails[];
  txFee: string;
  deductedTax?: string;
}

Attributes

Attribute / Type / Description

chain (string)

Blockchain from which the request was made.

network (string)

Network from which the request was made.

Request status. Can be either of:

STATUS.INPROGRESS: request is in flight.
STATUS.SUCESSFUL: request was successfully processed.
STATUS.UNSUCESSFUL: request failed.

Request type. Can be either of:

deposit: request is a transaction that deposits stablecoins to Anchor.
withdraw: request is a transaction that withdraws stablecoins from Anchor.
send: request is a transaction that sends tokens to a different account.

currency (string)

Currency of token (stablecoin or their aTerra counterpart).

amount (string)

Amount of currency tokens utilized in the request.

Transaction details.

txFee (string)

Amount of transaction fees spent by the requester.

deductedTax (string)

Amount of stablecoins that were deducted from the deposit / withdraw amount.

Deduction can occur from three causes:

Stablecoin Swap Fees - value lost as fees / slippage during conversion.

Applies only for withdrawals on Terra, and deposits / withdrawals to / from outside the Terra blockchain (e.g. Ethereum).

STATUS

Represents the progress status of a previously made request.

export enum STATUS {
  INPROGRESS = 'in-progress', 
  SUCCESSFUL = 'successful',
  UNSUCCESSFUL = 'unsuccessful',
}

Enum Member

Description

INPROGRESS

Request is in flight

SUCCESSFUL

Request was successfully processed

UNSUCCESSFUL

Request failed

TxType

Represents the type of a request.

export enum TxType {
  DEPOSIT = 'deposit',
  WITHDRAW = 'withdraw',
  SEND = 'send',
}

Enum Member

Description

DEPOSIT

Request is a transaction that deposits stablecoins to Anchor

WITHDRAW

Request is a transaction that withdraws stablecoins from Anchor

SEND

Request is a transaction that sends tokens to a different account

TxDetails

Represents the details of a transaction.

export interface TxDetails {
  chain: string;
  height: number;
  timestamp: Date;
  txHash: string;
}

Attributes

Attribute / Type / Description

chain (string)

Blockchain on which the transaction occurred on.

height (number)

Block height of the block that the transaction was included.

timestamp (Date)

Timestamp when the transaction was included in a block.

txHash (string)

Transaction hash of the transaction.

BalanceOutput

The BalanceOutput namespace represents your balance.

export interface BalanceOutput {
    chain: string; 
    network: string;
    height: number;
    timestamp: Date;
    address: string;
    balances: BalanceEntry[];
    total_account_balance_in_ust: string;
    total_deposit_balance_in_ust: string;
}

Attributes

Attribute / Type / Description

chain (string) Blockchain that the account resides on.

network (string)

Network that the account resides on.

height (number)

Block height when the information was queried from the blockchain.

timestamp (Date)

Timestamp when the information was queried from the blockchain.

address (string)

Address of the account that was used to retrieve its balance.

Balance information.

total_account_balance_in_ust (string)

Total value of account's stablecoin balance valued in UST.

total_deposit_balance_in_ust (string)

Total value of account's deposit balance valued in UST.

BalanceEntry

Represents balance information for a specific stablecoin.

export interface BalanceEntry {
  currency: string;
  account_balance: string;
  deposit_balance: string;
}

Attributes

Attribute / Type / Description

currency (string)

Currency of stablecoin.

account_balance (string)

Account balance for this stablecoin.

deposit_balance (string)

Account's deposit balance for this stablecoin.

MarketOutput

Represents overall market information.

export interface MarketOutput {
    chain: string; 
    network: string;
    height: number;
    timestamp: Date;
    markets: MarketEntry[];
}

Attributes

Attribute / Type / Description

chain (string)

Blockchain that the market resides on.

network (string)

Network that the market resides on.

height (number)

Block height when the information was queried from the blockchain.

timestamp (Date)

Timestamp when the information was queried from the blockchain.

Market information.

MarketEntry

export interface MarketEntry {
  currency: string;
  liquidity: string;
  APY: string;
}

Attributes

Attribute / Type / Description

currency (string)

Currency of stablecoin.

liquidity (string)

Amount of stablecoins that are available for withdrawal.

Attempting to withdraw stablecoins in excess of this amount may lead to request failure.

APY (string)

Annualized yield for deposits of this stablecoin.

CustomSigner

A utility function that allows remote signing of transaction (e.g. Ledger Hardware Wallet, Custodian APIs). When provided, Anchor Earn would act as a message/unsignedTx generator, and all transaction creation and signing should be handled within the function. customSigner should throw an error if any step results in failures.

export interface CustomSigner<T, K> {
  customSigner?: (tx: T) => Promise<K>;
}

Generic Type Notation

Type

Description

T (Argument)

Msg[ ]

Terra message array used to create an unsigned transaction

K (Expected Output)

StdTx

Signed transaction

CustomBroadcaster

A utility function that allows remote signing and broadcasting of transaction (e.g. Web Wallet Extensions). When provided, Anchor Earn would act as a message generator, and all transaction creation & signing & broadcasting should be handled within the function. customBroadcaster should throw an error if any step results in failures.

export interface CustomBroadcaster<T, K> {
  customBroadcaster?: (tx: T) => Promise<K>;
}

Generic Type Notation

Type

Description

T (Argument)

Msg[ ]

Terra message array used to create an unsigned transaction

K (Expected Output)

string

Hash of broadcasted transaction

Loggable

A utility function that allows observation of the transaction progress. When provided, the function is called every time there is a state update to the transaction. Particularly useful in case of EthAnchor transactions (not supported in this version), as EthAnchor operations are asynchronous and there are multiple interim states.

export interface Loggable<T> {
  log?: (data: T) => Promise<void> | void;
}

Generic Type Notation

Type

Description

T (Argument)

Transaction progress data

K (Expected Output)

void

nil