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
objectoptions : Object
- privateKey :
Hex
|Uint8Array
|SigningKey
; the override 32 byte Ethereum standard private key used for signing transactions. Used instead of the provider signing usingeth_signTypedData_v4
. If you would like to resolve a mnemonic seed phrase, usenew 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 managesync
manually by usingawait wallet.sync()
, see Performance and Syncing for more details.
- privateKey :
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
, default100
seconds (or100000
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
});
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 ( [options] ) => Promise<TransactionResponse
>
Description
This will complete finalized withdrawals. Withdrawals must first be started using withdraw
.
Params
- 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({
// 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
; eitherinput
orerror
- listener :
Function
; a callback function which will include a single argument: aUTXO
,Root
orDeposit
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.
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 theRoot
,Deposit
orUTXO
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 thePromise
to either fail or be accepted - force :
Boolean
; force this method into a singleRoot
on Ethereum - sync :
Boolean
; do an accountsync
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.