Wallet SDK

new

new fuel . Wallet ( provider [, options ] )

Installation

node.js

npm install --save @fuel-js/wallet

browser (UMD)

<script src="https://unpkg.com/@fuel-js/wallet@latest/umd/fuel.umd.min.js" type="text/javascript">
</script>

browser (ESM)

<script type="module">
  import fuel from "https://unpkg.com/@fuel-js/wallet@latest/umd/fuel.umd.min.js";
</script>

Usage

import fuel from '@fuel-js/wallet';

// use the window provider key / account / eth_signTypedData_v4 for transaction signing
const wallet = new fuel.Wallet(window.web3.currentProvider);


(async () => {

  // make a deposit
  await wallet.deposit(daiAddress, fuel.utils.parseEther('1.0'));

  // make a transfer
  await wallet.transfer(daiAddress, recipientAddress, fuel.utils.parseEther('1.0'));

  // listen for new inputs and balance changes
  wallet.on('input', input => {
    console.log('listening for new inputs: ', input);
  });

  // get your address
  console.log('my address', wallet.address);

})();

Description

The Wallet object allows you to interact with a Fuel instance.

This object is heavily powered by the ethers library. web3.js providers are also supported.

The Wallet wrapper will simply use the provided provider object's ethsignTypedDatav4 method for signing transactions.

If neither are available, you can use the Wallet object as a read-only wallet. You may also provide an override privateKey which will be used in place of the provider. The storage and management of this privateKey is up to the developer.

Ethereum gasPrice and gasLimit options are only needed when using the force feature of SDK methods, which will allow users the option of creating their own rollup blocks.

Params

provider : Web3Provider | EthersProvider; a web3 or ethers Provider object
options : Object
- privateKey : Hex | Uint8Array | SigningKey; the override 32 byte Ethereum standard private key used for signing transactions. Used instead of the provider signing using eth_signTypedData_v4. If you would like to resolve a mnemonic seed phrase, use new ethers.Wallet.fromMnemonic
- gasPrice : Hex | BigNumber; the Ethereum gas price for forced transactions
- gasLimit : Hex | BigNumber; the Ethereum gas limit for forced transactions
- address : Hex; the read-only 20-byte hex string address for watching balances
- db : LevelDown; a leveldown-compliant database instance for storing inputs and outputs temporarily or persistently
- sync : Boolean; sync before each wallet action, this can be turned off for better performance but you will have to manage sync manually by using await wallet.sync(), see Performance and Syncing for more details.

Throws

If the db is invalid or will not open
If the privateKey is invalid or incorrect, if provided

const wallet = new fuel.Wallet(window.web3.currentProvider, {
  db: require('level-js')(), // a leveldown-compliant database
});

deposit

wallet . deposit ( token, amount [, options] ) => Promise<TransactionResponse>

Description

The deposit method will deposit ERC-20 tokens or ETH into the Fuel.

Params

token : Hex; Number; BigNumber; the 20-byte ERC-20 token address or ID number
amount : Number | Hex | BigNumber; the amount to deposit into Fuel
options : OptionsObject

Returns

This method returns a TransactionResponse object.

response : TransactionResponse; the transaction response object

Throws

If there is insufficient balance of the ERC-20 token or ETH to cover amount and gas fees
If the timeout has passed and no Fuel block producer has picked up the deposit

await wallet.deposit(daiAddress, 500000, {
  // gasPrice: ...,
  // gasLimit: ...,
  // from: '0x...',
  // timeout: 10000, // seconds
});

faucet

wallet . faucet ( [, options] ) => Promise

Description

This method will call the Fuel network faucet, based upon your network, and send the wallet.address test tokens to play with.

Note, this method might take up to a few minutes to work and is rate-limited.

Params

options : OptionsObject

Throws

If the options.timeout, default 100 seconds (or 100000 micro-seconds) times out.

await wallet.faucet();

balance

wallet . balance ( token, [, options] ) => Promise<BigNumber>

Description

This method will give you your current balance for a specific token.

Params

token : Hex; Number; BigNumber; the 20-byte ERC-20 token address or ID number
options : OptionsObject

Returns

This method returns a BigNumber object containing the balance.

balance : BigNumber; the balance for the token

Throws

If the token is invalid or is not registered with Fuel

await wallet.balance(daiAddress);

transfer

wallet . transfer ( token, to, amount [, options] ) => Promise<TransactionResponse>

Params

token : Hex; Number; BigNumber; the 20-byte ERC-20 token address or ID number
to : Hex; the 20-byte recipient address
amount : Number | Hex | BigNumber; the amount to transfer
options : OptionsObject

Returns

This method returns a TransactionResponse object.

response : TransactionResponse; the transaction response object

Throws

If there is insufficient balance of the ERC-20 token or ETH to cover amount and fees
If there is a connection or provider issue

await wallet.transfer(daiAddress, someAddress, 250000, {
  // inputs: [], // specify explicit array of UTXO IDs to spend
  // feeLimit: 2000,
  // from: '0x....',
  // gasPrice: ..., // only used if forcing a tx
  // gasLimit: ..., // only used if forcing a tx
  // force: true, // will attempt for force tx on-chain
  // htlc: true, // will create an HTLC transfer
  // preImage: '0x....', // a 32 byte sha256 pre-image for the transfer
  // expiry: 5000000, // the Ethereum block number which the HTLC will expire
});

withdraw

wallet . withdraw ( token, amount [, options] ) => Promise<TransactionResponse>

Description

This function allows you to start a long withdraw from Fuel. You first send the withdraw transaction on Fuel, then you complete the withdrawal on Ethereum 2 weeks later.

Params

token : Hex; Number; BigNumber; the 20-byte ERC-20 token address or ID number
amount : Number | Hex | BigNumber; the amount to withdraw
options : OptionsObject

Returns

This method returns a TransactionResponse object.

response : TransactionResponse; the transaction response object

Throws

If there is insufficient balance of the ERC-20 token or ETH to cover amount and fees
If there is a connection or provider issue

await wallet.withdraw(daiAddress, 250000, {
  // inputs: [], // specify explicit array of UTXO IDs to spend
  // feeLimit: 2000,
  // from: '0x....',
  // gasPrice: ..., // only used if forcing a tx
  // gasLimit: ..., // only used if forcing a tx
  // force: true, // will attempt for force tx on-chain
});

retrieve

wallet . retrieve ( tokenId, [options] ) => Promise<TransactionResponse>

Description

This will complete finalized withdrawals. Withdrawals must first be started using withdraw.

Params

tokenId : Hex; Number; BigNumber;
options : OptionsObject

Returns

This method returns a TransactionResponse object.

response : TransactionResponse; the transaction response object

Throws

If there is insufficient balance of the ERC-20 token or ETH to cover amount and gas fees
If there is a connection or provider issue

// after 2 weeks...
await wallet.retrieve(0, {
  // inputs: [], // specify explicit array of utxo hashes to retrieve
  // from: '0x....',
  // gasPrice: ..., // only used if forcing a tx
  // gasLimit: ..., // only used if forcing a tx
});

sync

wallet . sync ( [options] ) => Promise<Void>

Description

The sync method will simply download the current UTXOs for this wallet from the Fuel provider.

Throws

If there is a connection or provider issue
If there was an issue getting the private account via eth_getAccounts
If there was an issue getting the current Ethereum network from the provider

  // sync your wallet with the Fuel api
  await wallet.sync();

on

wallet . on ( type, listener )

Description

The on method is used to register listeners for incoming transactions from the Fuel API. Once an on listener is registered, the wallet becomes live, and balances will automatically update.

If there is a problem with the listener at any time or it fails to bind, the error type will be used.

Params

type : String; either input or error
listener : Function; a callback function which will include a single argument: a UTXO, Root or Deposit proof object

wallet.on('input', utxoOrRootProof => {
  console.log(utxoOrRootProof);
});

wallet.on('error', error => {
  console.log(error);
});

fee

wallet . fee ( token ) => Promise<BigNumber>

Description

Get the current feerate for an ERC-20 token per byte.

Params

token : Hex; Number; BigNumber; the 20-byte ERC-20 token address or ID number

Returns

fee : BigNumber; the feerate for this ERC-20 token

Throws

If this token has no feerate available, i.e. the Fuel operator has not allowed this token yet

  // get the current fee for processing a specific token
  await wallet.fee(daiAddress);

Performance and Syncing

Note, that the Wallet by default will sync before each action (i.e. transfer, balance etc), you may turn this off by setting { ..., sync: false } in either the global wallet options or per each method.

If you do this, you must manually manage sync operations using the wallet.sync() method when needed (e.g. upon account load or when the wallet balance is zero).

Objects

OptionsObject

inputs : Array [ Hex, ... ]; an array of 32-byte hex values specifying either the Root, Deposit or UTXO IDs you would like to spend
feeLimit: BigNumber; the maximum feerate to accept for submitting the transaction
gasPrice : Hex | BigNumber; the Ethereum gas price for forced transactions
gasLimit : Hex | BigNumber; the Ethereum gas limit for forced transactions
from : Hex; the 20-byte sender address to specify either the provider signer or the override private key
timeout : Number; the timeout to wait in seconds for the Promise to either fail or be accepted
force : Boolean; force this method into a single Root on Ethereum
sync : Boolean; do an account sync before the given method or action.

UTXO

transactionId : Hex;
outputIndex : BigNumber;
outputType : BigNumber;
owner : Hex;
amount : BigNumber;
token : BigNumber;
digest : Hex;
expiry : BigNumber;
returnOwner : Hex;

Root

producer : Hex;
merkleTreeRoot : Hex;
commitmentHash : Hex;
length : BigNumber;
feeToken : BigNumber;
fee : BigNumber;

Deposit

owner : Hex;
token : BigNumber;
blockNumber : BigNumber;
value : BigNumber;

BigNumber

This is an ethers wrapped BigNumber object, using BN.js under the hood.

Response Objects

TransactionResponse

transactionId : Hex; the Ethereum transaction hash
receipts : Array; an array of Ethereum transactions receipts, if any. Namely for deposits, withdrawals or forced transfers.

Edit this page

Previous

Running a Node

Next

Fuel Overview