Using Vaults (2.x+)

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.

Overview

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.

API

sendFromVault nfd

post

https://api.nf.domainshttps://api.testnet.nf.domainshttps://api.betanet.nf.domainshttp://localhost:80

/nfd/vault/sendFrom/{name}

Send an amount of an asset [0 == ALGO] to another account FROM the NFD Vault. Only owner of NFD can send.

Path parameters

namestring · min: 1 · max: 120RequiredExample: silvio.algoPattern: ^.+\.algo$

Body

application/json

amountinteger · max: 100000000000000Required

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

Example: 21430180502795

assetsinteger[] · min: 1 · max: 112Required

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.

Example: [2566731755297186000,2229230266104031200]

notestring · max: 1000Optional

Optional note to include in asset send transaction

Default: ""Example: xqz

receiverstringRequired

Algorand account or NFD Name (if vault destination) the asset(s) should be sent to

Example: Ut et ea vitae.

receiverCanSignbooleanOptional

Specifies that the receiver account is something the caller can sign for. If specified, then opt-in transactions it signs may be included

Default: falseExample: true

receiverTypestring · enumOptional

Account or NFD Vault the asset should be sent to (if allowed)

Default: accountExample: nfdVaultPossible values:

senderstringRequired

Sender of transaction, must be NFD owner

Example: 3JZA6WOUH5HMFR4U7F66R74DB53DN5EA6F3FG2UOVSNZWZTFRU6JNNOBX2Pattern: ^[A-Z2-7]{58}$

Responses

200

Returns array of paired values representing a transaction group to submit to an Algorand node. U or S for unsigned or signed, followed by the base64-encoded message-pack of an unsigned transaction (to be signed by sender/buyer) or a signed transaction to be submitted as-is.

application/json

ResponsestringExample: Velit qui qui tenetur.

400

invalidAddress: invalidAddress is returned for an Algorand address that doesn't appear to be valid

application/vnd.goa.error

403

vaultLocked: the target vault is locked, doesn't already have this asset, and won't accept it

application/vnd.goa.error

404

notFound: Not Found response.

application/vnd.goa.error

429

rateLimited: Too Many Requests response.

application/json

post

/nfd/vault/sendFrom/{name}

HTTPcURLJavaScriptPython

POST /nfd/vault/sendFrom/{name} HTTP/1.1
Host: api.nf.domains
Content-Type: application/json
Accept: */*
Content-Length: 246

{
  "amount": 34772186958805,
  "assets": [
    13992502780418464000
  ],
  "note": "sgm",
  "receiver": "Perspiciatis est autem praesentium quidem.",
  "receiverCanSign": false,
  "receiverType": "nfdVault",
  "sender": "DWVJ7JWRA574PKRFMJF47W6RMWW4FVAPVBQ4I5Y3MYTJIN4LTN5F2EMBGV"
}

Ad in.

sendToVault nfd

post

https://api.nf.domainshttps://api.testnet.nf.domainshttps://api.betanet.nf.domainshttp://localhost:80

/nfd/vault/sendTo/{name}

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

Path parameters

namestring · min: 1 · max: 120RequiredExample: silvio.algoPattern: ^.+\.algo$

Body

application/json

amountinteger · max: 100000000000000Required

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

Example: 82202057335358

assetsinteger[] · min: 1 · max: 64Required

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)

Example: [10185069543127515000]

notestring · max: 1000Optional

Optional note to include in asset send transaction

Default: ""Example: 3ms

optInOnlybooleanRequired

Whether to only opt-in to the asset, instead of including asset transfer txn

Default: falseExample: true

senderstringRequiredExample: FJHNELY2MXD45ETZIUHMVERKPYIYC7OTXJV4WMLSNTIZNXNPJFPIJTGIXFPattern: ^[A-Z2-7]{58}$

Responses

200

Returns array of paired values representing a transaction group to submit to an Algorand node. U or S for unsigned or signed, followed by the base64-encoded message-pack of an unsigned transaction (to be signed by sender/buyer) or a signed transaction to be submitted as-is.

application/json

ResponsestringExample: Laborum voluptatem quaerat.

400

invalidAddress: invalidAddress is returned for an Algorand address that doesn't appear to be valid

application/vnd.goa.error

403

vaultLocked: the vault is locked, doesn't already have this asset, and won't accept it

application/vnd.goa.error

404

notFound: Not Found response.

application/vnd.goa.error

413

tooManyTransactions: The number of transactions allowed in a single transaction group (16) have been exceeded.

application/vnd.goa.error

429

rateLimited: Too Many Requests response.

application/json

post

/nfd/vault/sendTo/{name}

HTTPcURLJavaScriptPython

POST /nfd/vault/sendTo/{name} HTTP/1.1
Host: api.nf.domains
Content-Type: application/json
Accept: */*
Content-Length: 157

{
  "amount": 97393843664364,
  "assets": [
    1426464794803608300
  ],
  "note": "abd",
  "optInOnly": false,
  "sender": "O73IKLOJ3Y4FUREGHB5CQRA47U4HWHFHHQ5HZHIOZJHLF47G47M6XTIEXG"
}

Omnis esse qui eveniet error hic.

TypeScript Example

Setup

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:

npm install axios @txnlab/use-wallet

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.

// src/api.ts

import axios from 'axios'

const API_BASE_URL = 'https://api.nf.domains'

interface SendToVaultRequestBody {
  /* 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 */
  amount: number
  /* 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) */
  assets: number[]
  /* Optional note to include in asset send transaction */
  note?: string
  /* Whether to only opt-in to the asset, instead of including asset transfer txn */
  optInOnly: boolean
  /* Sender of transaction, an Algorand account */
  sender: string
}

export function sendToVault(name: string, data: SendToVaultRequestBody) {
  return axios<string>({
    url: `${API_BASE_URL}/nfd/vault/sendTo/${name}`,
    method: 'post',
    headers: { 'Content-Type': 'application/json' },
    data
  })
}

interface SendFromVaultRequestBody {
  amount: number
  /* 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 receiver is a 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 receiver is already opted-in, then 112 (7 per txn, 16 tnxs) is
  max. */
  assets: number[]
  /* Optional note to include in asset send transaction */
  note?: string
  /* Algorand account or NFD Name (if vault receiver) the asset(s) should be sent to */
  receiver: string
  /* Specifies that the receiver account is something the caller can sign for. If specified, then
  opt-in transactions it signs may be included */
  receiverCanSign?: boolean
  /* Account or NFD Vault the asset should be sent to (if allowed) */
  receiverType?: 'account' | 'nfdVault'
  /* Sender of transaction, must be NFD owner */
  sender: string
}

export function sendFromVault(name: string, data: SendFromVaultRequestBody) {
  return axios<string>({
    url: `${API_BASE_URL}/nfd/vault/sendFrom/${name}`,
    method: 'post',
    headers: { 'Content-Type': 'application/json' },
    data
  })
}

Send To Vault

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

// src/sendToVault.tsx

import React from 'react'
import {
  useWallet,
  encodeNFDTransactionsArray,
  TransactionsArray
} from '@txnlab/use-wallet'
import { sendToVault } from './api'

export default function SendToVaultDemo() {
  const wallet = useWallet()
  const { activeAddress } = wallet

  async function signAndSendTransactions() {
    const NFD_NAME = 'doug.algo'
    const ASSET_ID = 212389838
    const AMOUNT = 1

    try {
      if (!activeAddress) {
        throw new Error('No account connected')
      }

      const response = await sendToVault(NFD_NAME, {
        sender: activeAddress,
        assets: [ASSET_ID],
        amount: AMOUNT,
        optInOnly: false
      })

      if (typeof response.data !== 'string') {
        throw new Error('Failed to fetch transactions')
      }

      const transactionsArray = JSON.parse(response.data) as TransactionsArray
      const signedTransactions = await wallet.signTransactions(
        encodeNFDTransactionsArray(transactionsArray)
      )

      const { id } = await wallet.sendTransactions(signedTransactions)

      console.log(
        `Successfully sent asset ${ASSET_ID} to ${NFD_NAME}'s vault!`,
        `Transaction ID: ${id}`
      )
    } catch (error) {
      console.error(`Send to vault failed`, error)
    }
  }

  if (!activeAddress) {
    return <p>Connect an account first.</p>
  }

  return (
    <div>
      <button type="button" onClick={signAndSendTransactions}>
        Sign and send transactions
      </button>
    </div>
  )
}

Send From Vault

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

// src/sendFromVault.tsx

import React from 'react'
import {
  useWallet,
  encodeNFDTransactionsArray,
  TransactionsArray
} from '@txnlab/use-wallet'
import { sendFromVault } from './api'

export default function SendFromVaultDemo() {
  const wallet = useWallet()
  const { activeAddress } = wallet // must match the NFD's `owner` account

  async function signAndSendTransactions() {
    const NFD_NAME = 'doug.algo'
    const ASSET_ID = 212389838
    const AMOUNT = 1
    const RECEIVER = 'receiver-address' // replace with valid Algorand account

    try {
      if (!activeAddress) {
        throw new Error('No account connected')
      }

      const response = await sendFromVault(NFD_NAME, {
        assets: [ASSET_ID],
        amount: AMOUNT,
        receiver: RECEIVER,
        receiverType: 'account'
      })

      if (typeof response.data !== 'string') {
        throw new Error('Failed to fetch transactions')
      }

      const transactionsArray = JSON.parse(response.data) as TransactionsArray
      const signedTransactions = await wallet.signTransactions(
        encodeNFDTransactionsArray(transactionsArray)
      )

      const { id } = await wallet.sendTransactions(signedTransactions)

      console.log(
        `Successfully sent asset ${ASSET_ID} from ${NFD_NAME}'s vault!`,
        `Transaction ID: ${id}`
      )
    } catch (error) {
      console.error(`Send from vault failed`, error)
    }
  }

  if (!activeAddress) {
    return <p>Connect an account first.</p>
  }

  return (
    <div>
      <button type="button" onClick={signAndSendTransactions}>
        Sign and send transactions
      </button>
    </div>
  )
}

Sequence diagram of calls

Resources

• Vaults Documentation

• NFDomains API Documentation

• Mainnet API Swagger Docs