Anchor Earn SDK

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

or

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
chain (CHAINS) Required Blockchain to interact from. For Anchor Earn v1.0, only CHAINS.TERRA (Terra blockchain) is supported.
network (NETWORKS) Required Network to interact in.
privateKey (Buffer | any) Optional Account private key.
mnemonic (string | any) Optional Account mnemonics.
address (string) Optional Account address. Required if transactions are to be signed / broadcasted remotely with the use of customSigner or customBroadcaster.

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
chain (CHAINS) Required 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 (DENOMS) Required Currency of stablecoin to deposit.
amount (string) Required Amount of stablecoins to deposit.
CustomSigner (callback function => StdTx) Optional 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. Expects StdTx, a transaction object used by the Terra blockchain (imported from Terra.js).
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 (DENOMS) Required Currency of stablecoin to withdraw or their aTerra counterpart.
amount (string) Required Amount of stablecoins (or their aTerra counterpart) to withdraw.
CustomSigner (callback function => StdTx) Optional 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. Expects StdTx, a transaction object used by the Terra blockchain (imported from Terra.js).
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 (DENOMS) Required 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. Expects StdTx, a transaction object used by the Terra blockchain (imported from Terra.js).
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
currencies (array of DENOMS) Required 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
currencies (array of DENOMS) Required 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	Terra blockchain

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:

Terra

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:

Terra

Mainnet

Denomination	Code	Decimals	Contract Address
UST	uusd	6	Native Token
aUST	uaust	6	terra1hzh9vpxhsk8253se0vv5jj6etdvxu3nv8z07zu

Testnet

Denomination	Code	Decimals	Contract Address
UST	uusd	6	Native Token
aUST	uaust	6	terra1ajt556dpzvjwl0kl5tzku3fc3p3knkg9mkv8jl

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
chain (CHAINS) Blockchain from which the request was made.
network (NETWORKS) Network from which the request was made.
status (STATUS) Request status. Should display UNSUCCESSFUL as the request encountered an error.
type (TxType) 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.
status (STATUS) Request status. Can be either of: STATUS.INPROGRESS: request is in flight. STATUS.SUCESSFUL: request was successfully processed. STATUS.UNSUCESSFUL: request failed.
type (TxType) 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.
txDetails (array of TxDetails) 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: Taxes - fees charged on Terra transactions. Shuttle Fees - fees charged on interchain token transfers. 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.
balances (array of BalanceEntry) 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.
markets (Array of MarketEntry) 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>;
}

Terra

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>;
}

Terra

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;
}

Terra

Generic Type Notation	Type	Description
T (Argument)	Output	Transaction progress data
K (Expected Output)	void	nil