Using Vaults (2.x+)
Last updated
Last updated
In this guide we will provide an example of how to use the NFDomains API to send assets to and from an NFD's vault, as a reference for adding Vault support in your own application.
A vault is an Algorand account controlled by an NFD's smart contract that can automatically opt-in to assets it receives.
The vault account is the 'nfdAccount' property in all NFDs. It is the contract account of the NFD itself. As each NFD is a distinct contract instance, each NFD has its own account - its vault.
Sending TO a vault (or account) using the API will check if the receiver is already opted-in and just provide a transfer transaction instead. If the receivers vault is not opted-in and is unlocked (or you're the owner of the vault), then the API returns transactions to have the vault opt-in. The transactions will pay the MBR (.1 per asset) of the assets being sent, and then vault_optin
calls to the vault to opt-in each of the assets, followed by asset transfers to the vault.
Sending FROM a vault follows a similar process, with the distinction that the receiverType
must be designated as either a standard 'account'
or another 'nfdVault'
.
Vaults are locked by default, meaning only the NFD's owner can send assets to it. When the owner unlocks the vault, anyone can send assets to it. The owner can lock or unlock the vault at any time.
In this example we will create two very basic React components that will prompt the user to sign transactions for sending an asset to and from an NFD's vault.
We will use Axios for handling HTTP requests to fetch the transactions, and the @txnlab/use-wallet
library to sign and send the transactions. Make sure these libraries are installed in your project:
Note: @txnlab/use-wallet
is not required, but it is used in this example to simplify the process of signing and sending transactions. See https://github.com/TxnLab/use-wallet for full setup instructions.
First we define functions for making requests to the NFD Vaults API using Axios. The sendToVault
and sendFromVault
functions will make POST requests to the /nfd/vault/sendTo/{name}
and /nfd/vault/sendFrom/{name}
endpoints, respectively.
Using the sendToVault
function, we create a component that prompts the user to sign and send transactions for sending an asset to an NFD's vault.
If the sender is not the owner, the receiving vault must be unlocked to auto opt-in and receive assets
If the vault is locked, only the NFD owner can send assets to it
The NFD must be upgraded to smart contract version 2.6 or higher to receive vault assets
Using the sendFromVault
function, we create a component that prompts the user to sign and send transactions for sending an asset from the vault of an NFD they own.
The transactions must be signed by the NFD's owner
account
The receiver
can be either an Algorand account or another NFD's vault (same rules described above apply to a receiving vault)
The NFD must be upgraded to smart contract version 2.6 or higher
Send an amount of an asset [0 == ALGO] to another account FROM the NFD Vault. Only owner of NFD can send.
/nfd/vault/sendFrom/{name}
silvio.algo
^.+\.algo$
Base amount (in base units of specified asset - so decimals must be considered) of asset to send. If multiple assets are specified, amount is should be 0 as ALL of each are sent and closed out
21430180502795
Algorand ASA IDs to transfer FROM vault - use asset 0 to send ALGO. Specifying multiple assets means ALL of each are sent and amount is ignored. If destination is vault and needs to opt-in, then need MBR/opt-in pairs (5 pairs - 8 opt-ins each - 40 assets), then 6 send calls of 7 assets w/ 5 at end for total of 40. If destination is already opted-in, then 112 (7 per txn, 16 tnxs) is max.
[2566731755297186000,2229230266104031200]
Optional note to include in asset send transaction
xqz
Algorand account or NFD Name (if vault destination) the asset(s) should be sent to
Ut et ea vitae.
Specifies that the receiver account is something the caller can sign for. If specified, then opt-in transactions it signs may be included
true
Account or NFD Vault the asset should be sent to (if allowed)
nfdVault
account
, nfdVault
Sender of transaction, must be NFD owner
3JZA6WOUH5HMFR4U7F66R74DB53DN5EA6F3FG2UOVSNZWZTFRU6JNNOBX2
^[A-Z2-7]{58}$
Provide transaction to send an asset owned by sender account to an NFD vault. Call to have opt-in to vault will be included if necessary. Callable by NFD owner, or if Opt-in is UNLOCKED (or asset already opted-in), anyone can call
/nfd/vault/sendTo/{name}
silvio.algo
^.+\.algo$
Base amount (in base units of specified asset - so decimals must be considered) of asset to send. If multiple assets specified, amount is ignored and ALL of each are sent
82202057335358
Algorand ASA IDs to transfer (and opt-in inside vault if necessary) - use asset 0 to send ALGO. Specifying multiple assets means ALL of each are sent and amount is ignored. 13 is max assets that can be specified if they're being sent (2 for MBR payments, 2 for opt-in txns (8+4 asset opt-ins), 12 asset transfers). If opt-in only then 64 is maximum (1 MBR per 8 assets, 8 assets per txn * 8 txns)
[10185069543127515000]
Optional note to include in asset send transaction
3ms
Whether to only opt-in to the asset, instead of including asset transfer txn
true
FJHNELY2MXD45ETZIUHMVERKPYIYC7OTXJV4WMLSNTIZNXNPJFPIJTGIXF
^[A-Z2-7]{58}$