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:
1
npm install -S @anchor-protocol/anchor-earn
Copied!
or
1
yarn add @anchor-protocol/anchor-earn
Copied!
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
1
const anchorEarn = new AnchorEarn({
2
  chain: CHAINS.TERRA,
3
  network: NETWORKS.BOMBAY_12,
4
  mnemonic: '...',
5
});
Copied!
​
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
1
// generate a new Terra account 
2
const account = new Account(CHAINS.TERRA); 
Copied!
The Account instance contains the information for the newly created account.
1
export class Account {
2
  accAddress: AccAddress;
3
  publicKey: string;
4
  privateKey: Buffer;
5
  mnemonic: string;
6
}
Copied!
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.
1
import { Wallet, MnemonicKey } from '@anchor-protocol/anchor-earn';
2
const account = new MnemonicKey({
3
  mnemonic: '...',
4
});
Copied!
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
1
const deposit = await anchorEarn.deposit({
2
  currency: DENOMS.UST,
3
  amount: '12.345', // 12.345 UST or 12345000 uusd
4
});
Copied!
​
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
1
const withdraw = await anchorEarn.withdraw({
2
  currency: DENOMS.UST,
3
  amount: '12.345', // 12.345 UST or 12345000 uusd
4
});
Copied!
​
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
1
const sendUst = await anchorEarn.send({
2
  currency: DENOMS.UST, 
3
  recipient: 'terra1...', 
4
  amount: '12.345', // 12.345 UST or 12345000 uusd
5
});
Copied!
​
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
1
const balanceInfo = await anchorEarn.balance({
2
  currencies: [
3
    DENOMS.UST
4
  ],
5
});
Copied!
​
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
1
const marketInfo = await anchorEarn.market({
2
  currencies: [
3
    DENOMS.UST
4
  ],
5
});
Copied!
Resources
CHAINS
The CHAINS enumerated type specifies blockchains that are supported by Anchor Earn. 
1
export enum CHAINS {
2
  TERRA = 'terra',
3
}
Copied!
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. 
1
export enum NETWORKS {
2
  COLUMBUS_5,
3
  BOMBAY_12,
4
}
Copied!
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.
1
export enum DENOMS {
2
  UST = 'uusd',
3
  AUST = 'uaust',
4
}
Copied!
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.
1
export interface OperationError {
2
  chain: string;
3
  network: string;
4
  status: STATUS;
5
  type: TxType;
6
  error_msg: string;
7
}
Copied!
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.
1
export interface Output {
2
  chain: string;
3
  network: string;
4
  status: STATUS;
5
  type: TxType;
6
  currency: string;
7
  amount: string;
8
  txDetails: TxDetails[];
9
  txFee: string;
10
  deductedTax?: string;
11
}
Copied!
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.
1
export enum STATUS {
2
  INPROGRESS = 'in-progress', 
3
  SUCCESSFUL = 'successful',
4
  UNSUCCESSFUL = 'unsuccessful',
5
}
Copied!
Enum Member
Description
INPROGRESS
Request is in flight
SUCCESSFUL
Request was successfully processed
UNSUCCESSFUL
Request failed
​
TxType
Represents the type of a request.
1
export enum TxType {
2
  DEPOSIT = 'deposit',
3
  WITHDRAW = 'withdraw',
4
  SEND = 'send',
5
}
Copied!
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.
1
export interface TxDetails {
2
  chain: string;
3
  height: number;
4
  timestamp: Date;
5
  txHash: string;
6
}
Copied!
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. 
1
export interface BalanceOutput {
2
    chain: string; 
3
    network: string;
4
    height: number;
5
    timestamp: Date;
6
    address: string;
7
    balances: BalanceEntry[];
8
    total_account_balance_in_ust: string;
9
    total_deposit_balance_in_ust: string;
10
}
Copied!
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.
1
export interface BalanceEntry {
2
  currency: string;
3
  account_balance: string;
4
  deposit_balance: string;
5
}
Copied!
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. 
1
export interface MarketOutput {
2
    chain: string; 
3
    network: string;
4
    height: number;
5
    timestamp: Date;
6
    markets: MarketEntry[];
7
}
Copied!
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
1
export interface MarketEntry {
2
  currency: string;
3
  liquidity: string;
4
  APY: string;
5
}
Copied!
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.  
1
export interface CustomSigner<T, K> {
2
  customSigner?: (tx: T) => Promise<K>;
3
}
Copied!
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.  
1
export interface CustomBroadcaster<T, K> {
2
  customBroadcaster?: (tx: T) => Promise<K>;
3
}
Copied!
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.
1
export interface Loggable<T> {
2
  log?: (data: T) => Promise<void> | void;
3
}
Copied!
Terra
Generic Type Notation
Type
Description
T (Argument)
​Output​
Transaction progress data
K (Expected Output)
void
nil
EthAnchor - Previous
Fees
Next - Developers - Earn
Example Usage
Last modified 17d ago