Overview

Config and Setup

Initialise and set up the client to connect to its necessary third-party services to fulfil basic functionality. The third-party services used must be at a minimum to fulfil the wallet functionality, such as displaying balances and sending transactions.

During configuration, the following can be passed in:

  • Network choice (default is MAINNET)
  • Phrase (mandatory)
  • Service Keys (optional, if null, client will use config defaults or free service limits.)

Service keys can also be configured by environment variables. The supported ones are:

  • ETHERSCAN_API_KEY. Used by the ETH client to connect to the Etherscan API service.
  • ARBISCAN_API_KEY. Used by the Arbitrum client to connect to the Arbiscan API service.
  • SNOWTRACE_API_KEY. Used by the AVAX client to connect to the Snowtrace API service.
  • BSCSCAN_API_KEY. Used by the BSC client to connect to the Bscscan API service.
  • BLOCKCYPHER_API_KEY. Used by the BTC, LTC and DOGE to connect to the Blockcypher API service.
  • SOCHAIN_API_KEY. Used by the BTC, LTC and DOGE to connect to the Sochain API service.
  • COVALENT_API_KEY. Used to connect to the Covalent API service.

Set Network

Sets a type of NETWORK, which is either MAINNET or TESTNET.

enum Network {
  TEST = 'testnet',
  MAIN = 'mainnet',
}
setNetwork(net: Network): XChainClient

Returns the client.

Set Phrase

Sets the master BIP39 phrase, from which the private key is extracted and the address decoded.

setPhrase(phrase: string): address

The function should store the private key and address, then return the address generated by the phrase.

Querying

Querying the balances and the transaction history/data

Get Explorer URL

Returns the correctly formatted url string with paths for:

  • Addresses
  • Transactions

The default Explorer URL can be hard-coded, or passed in as a service. The object to be cast into the explorer link should be passed in as a string, like a transaction ID or an address.

enum Path {
  address = 'address',
  transaction = 'transaction',
}
getExplorerUrl(type: Path, param: string): string

The function should return the correctly formatted url string.

Example

https://blockchair.com/bitcoin/transaction/d11ff3352c50b1f5c8e2030711702a2071ca0e65457b40e6e0bcbea99e5dc82e
https://blockchair.com/bitcoin/address/19iqYbeATe4RxghQZJnYVFU4mjUUu76EA6

https://explorer.binance.org/tx/94F3A6257337052B04F9CC09F657966BFBD88546CA5C23F47AB0A601D29D8979
https://explorer.binance.org/address/bnb1z35wusfv8twfele77vddclka9z84ugywug48gn

https://etherscan.io/tx/0x87a4fa498cc48874631eaa776e84a49d28f42f01e22c51ff7cdfe1f2f6772f67
https://etherscan.io/address/0x8eb68e8f207be3dd1ec4baedf0b5c22245cda463

Get Balance

Returns the balance of an address.

  • If address is not passed, gets the balance of the current client address.
  • Optional asset can be passed, in which the query will be specific to that asset, such as ERC-20 token.
  • Returns an array of assets and amounts, with assets in chain notation CHAIN.SYMBOL-ID.
  • Converts to 8 decimal places for conformity.
getBalance(address?: Address, asset?: string): Promise<Balances>

Example of third-party service queries to get balances:

https://api.blockchair.com/bitcoin/addresses/balances?addresses=34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo
https://api.ethplorer.io/getAddressInfo/0xb00E81207bcDA63c9E290E0b748252418818c869?apiKey=freekey
https://dex.binance.org/api/v1/account/bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m

Example of returned array:

[
  { 
    "asset" : "BTC.BTC"
    "amount" : 100000000
  }
]

Get Transactions

Gets a simplied array of recent transactions for an address.

type TxHistoryParams = {
  address: Address // Address to get history for
  offset?: number // Optional Offset
  limit?: number // Optional Limit of transactions
  startTime?: Date // Optional start time
  asset?: string // Optional asset. Result transactions will be filtered by this asset
}
getTransactions(params?: TxHistoryParams): Promise<TxPage>

Example of third party services to help:

// get UTXOS for address
https://api.blockchair.com/bitcoin/outputs?recipient=34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo
// get tx details for each UTXO
https://api.blockchair.com/bitcoin/dashboards/transactions/ff0bd969cce99b8d8086e452d7b63167fc178680fee796fc742cb14a9a6ef929

https://api.ethplorer.io/getAddressTransactions/0xb297cacf0f91c86dd9d2fb47c6d12783121ab780?apiKey=freekey
https://dex.binance.org/api/v1/transactions?address=bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m

Example of return:

{
  "total": 1,
  "txs": [
    { 
      "asset" : "BTC.BTC",
      "from" : [
        {
          "from": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
          "amount": 100000000
        }
      ],
      "to" : [
        {
          "to": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
          "amount": 100000000
        }
      ],
      "date" : "2020-10-04T06:24:36.548Z",
      "type" : "transfer"
      "hash" : "980D9519CCB39DC02F8B0208A4D181125EE8A2678B280AF70666288B62957DAE",
    }
  ]
}

Get Transaction Data

Get a transaction information from the transaction ID/hash.

getTransactionData(txId: string): Promise<Tx>

Example of third party services to help:

https://blockchair.com/bitcoin/transaction/d11ff3352c50b1f5c8e2030711702a2071ca0e65457b40e6e0bcbea99e5dc82e
https://explorer.binance.org/tx/94F3A6257337052B04F9CC09F657966BFBD88546CA5C23F47AB0A601D29D8979
https://etherscan.io/tx/0x87a4fa498cc48874631eaa776e84a49d28f42f01e22c51ff7cdfe1f2f6772f67

Example of return:

{ 
  "asset" : "BTC.BTC",
  "from" : [
    {
      "from": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
      "amount": 100000000
    }
  ],
  "to" : [
    {
      "to": "34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo",
      "amount": 100000000
    }
  ],
  "date" : "2020-10-04T06:24:36.548Z",
  "type" : "transfer"
  "hash" : "980D9519CCB39DC02F8B0208A4D181125EE8A2678B280AF70666288B62957DAE",
}

Transactions

Making transfers.

Optional blockchain-specific transactions can be added here, such as Binance Chain multi-send.

Get Fees

This function calculates and returns the fee object in a generalised way for a simple transfer function. XChainJS userbase has high time preferences, so high fee rates are preferred.

Since this depends on optional third-party services, sensible defaults should be hardcoded if there are errors.

The fastest fee rate should be guaranteed next block (1.5x Fast), fast should be 1-2 blocks (1x next block fee rate), average should be 2-3 blocks (0.5x Fast). Don't over-complicate this. PoW blockchains have no guarantees.

  • Type should specify the units to display, or if flat fees, simply "flat". The client should interpret and display this, such as showing the user the fee rates and their units.
  • Fastest (target of next block)
  • Fast (target of 1-2 blocks)
  • Average (target of 2-3 blocks)

Third party services: Bitcoin - returns next block feeRate (fast). Use multiples of this to extrapolate to Fastest/Average. https://api.blockchair.com/bitcoin/stats

Ethereum - returns fastest/fast/average https://ethgasstation.info/api/ethgasAPI.json?api-key=XXAPI_Key_HereXXX

getFees(): Promise<Fees>
getDefaultFees(): Promise<Fees>

type Fees = {
  "type": "byte" | "base"
  "fastest": BaseAmount
  "fast": BaseAmount
  "average": BaseAmount
}

Transfer

General transfer function that should be signed and broadcast using a third party service. The fee should always be rate, which is units per transaction size. The size should be calculated on the fly or hardcoded:

  • Bitcoin: 250 bytes is typical, so feeRate of 10 is 10 sats per byte, eg, 2500 sats
  • Ethereum: gwei is standard, so a feeRate of 20 would be interpreted as 20 GWEI
  • Binance Chain: fixed size, so the feeRate is ignored.

Broadcast URLs

https://api.blockchair.com/{:chain}/push/transaction
https://dex.binance.org/api/v1/broadcast

type TxParams = {
  asset?: Asset // BTC.BTC
  amount: BaseAmount // in base format (10**8)
  recipient: Address // address
  memo?: string // optional memo to pass
}

transfer(params: TxParams): Promise<TxHash>

The function should return the hash of the finalised transaction.

Purge

When a wallet is "locked" the private key should be purged in each client by setting it back to null.

purgeClient()