5: Integrating with tokens
Overview
When building dapps on the BigFile, integrating tokens into your dapp may be necessary for enabling DeFi, governance, marketplace, or other tokenomic functions. There are several types of tokens in the BigFile ecosystem, such as the protocol's native token BIG, fungible tokens that use the BIGRC-1 or BIGRC-2 standards, and soon non-fungible tokens that will use the upcoming BIGRC-7 standard.
This tutorial will cover the different types of tokens and how to interact with them.
Fungible and non-fungible tokens
A fungible token is a type of token that can always be transferred 1:1 for another token of the same type.
A non-fungible token (NFT) is a tokenized asset that is assigned a unique identifier and cannot be exchanged 1:1 for another token of the same time, as the value of each non-fungible token may vary.
For example, 1 USD can always be exchanged for 1 USD. However, 1 unique painting cannot be exchanged for another unique painting, since the value of the two paintings will be different. On the BigFile, BIG is a fungible token that can always be exchanged for BIG of equal value. However, an non-fungible token deployed on BIG cannot be traded 1:1 with another NFT token deployed on BIG.
On the BigFile, there are several different token standards for both fungible tokens and non-fungible tokens. Some of these standards include:
BIGRC-1: A fungible token standard used to create custom fungible tokens on the BigFile. The BIGRC-1 standard was designed to create a universally accepted standard for creating and recording token transactions on the BigFile. The BIGRC-1 standard defines the general functionalities of ledgers; any tokens and their corresponding ledgers that want to support the BIGRC-1 standard must fulfill all requirements within the standard. A detailed account of the standard can be found here.
BIGRC-2: The BIGRC-2 standard is an extension of the BIGRC-1 standard that enables the approve-transfer-from pattern that became popular in the Ethereum ecosystem with the ERC-20 token standard. It specifies a way for an account owner to delegate token transfers to a third party, usually a canister, on the owner's behalf. A detailed account of the standard can be found here.
BIGRC-7: A new standard for non-fungible tokens on the BigFile. It is designed to be a minimal standard for allowing an NFT collection to be deployed on BIG. In an NFT collection, each NFT may have unique metadata information. This metadata may include a unique image, traits or tags, or a description describing the NFT. A detailed account of the standard can be found here.
BIG
BIG is the native token of the BigFile Protocol. BIG tokens have three key functionalities on the protocol:
Facilitating the network's governance through neuron staking.
Creating cycles by converting BIG into cycles, which are then used to pay for canister computation and resources.
Rewarding NNS participants by providing BIG tokens to users that stake BIG in neurons and actively participate in voting on proposals.
To interact with BIG tokens, you will need to use a specialized canister known as the BIG ledger. The ledger canister is used to hold ledger accounts and record a traceable history of all BIG transactions.
The BIG ledger supports the BIGRC-1 and BIGRC-2 standards, but also implements it's own standard that has significant differences when compared to the BIGRC-1 and BIGRC-2 standards, most notably around the notion of an Account.
The BIG ledger can only be used to interact with BIG tokens; to interact with other tokens, such as BIGRC tokens, the respective BIGRC ledger will need to be used.
Accounts
An account on the BIG ledger is identified by the AccountIdentifier value, which is a value derived from the account owner's BIG principal and subaccount. Accounts can only be owned by one principal; however, since a principal can refer to a canister, joint accounts can be implemented as a canister.
If you are familiar with an Ethereum or Bitcoin user's public key, a principal identifier can be thought of as the BIG equivalent. When you use a principal, your corresponding secret key is used to sign messages, authenticate with the ledger, and execute transactions on your account.
Transaction types
Within the BIG ledger canister, there are three types of transactions:
Minting: A minting transaction generates a new token for an account.
Burning: A burning transaction eliminates a token from existence.
Transferring: A transferring transaction transfers BIG between accounts.
Deploying the BIG ledger locally
Integrating your project with the BIG ledger can provide necessary functionality for dapps such as decentralized exchanges, token swaps, and other DeFi applications. To integrate with the BIG ledger, first it is recommended to test the integration in your local developer environment. You can learn how to deploy the BIG ledger locally in the documentation here.
Interacting with the BIG ledger on the mainnet
To interact with the BIG ledger, first you need to get your local ledger account ID with the command:
dfx ledger account-id
Then, to check the balance of that account, use the following command, replacing ACCOUNT_ID with the output from the dfx ledger account-id command:
dfx ledger --network ic balance ACCOUNT_ID
To interact with the mainnet ledger, you must use the --network ic flag. Otherwise, dfx will try to use the local replica.
To transfer BIG tokens from one account to another, use the following command, replacing AMOUNT with the number of BIG tokens to transfer, MEMO with a brief message to describe the reason for the transfer, and RECEIVER_ACCOUNT_ID with the account ID to receive the tokens:
dfx ledger transfer --amount AMOUNT --memo MEMO RECEIVER_ACCOUNT_ID
BIGRC-1 tokens
BIGRC-1 is a fungible token standard used to create custom fungible tokens on BIG. It was designed to create a universally accepted standard for creating and recording token transactions. The BIGRC-1 standard defines the general functionalities of ledgers; any tokens and their corresponding ledgers that want to support the BIGRC-1 standard must fulfill all requirements within the standard. A detailed account of the standard can be found here.
In comparison to BIG tokens, the BIG and BIGRC-1 ledgers use different endpoints, different transactions, different block objects, in addition to other subtle differences.
AccountIdentifiers
The BIG ledger uses AccountIdentifiers to represent accounts, which are essentially a hash of the BIGRC-1 Account value.
An Account can be converted into an AccountIdentifier, but an AccountIdentifier cannot be converted into an Account. This factor provides the BIG ledger with a level of anonymity, though it means the BIG ledger cannot have the same internal representation as an BIGRC-1 ledger.
Extensions of the standard
The BIGRC-1 standard intentionally excludes certain ledger functions that are necessary for building diverse DeFi applications, such as transaction notifications for smart contracts, an interface and structure for fetching blocks, and pre-signed transactions.
The BIGRC-1 standard defines the icrc1_supported_standards endpoint to accommodate these functions through extensions of the standard. This endpoint returns all specifications implemented by the ledger, such as BIGRC-2 or DIP-20.
Metadata
The BIGRC-1 token standard allows for several optional metadata fields to be specified. Metadata can be used to help improve the user experience and simplify the token's integration with wallets. Each metadata key is an arbitrary Unicode string that uses the format <namespace>:<key>, where the namespace icrc1 is reserved for metadata defined for the BIGRC-1 standard. Metadata entries include:
icrc1:symbol: The token's currency code, such asvariant { Text = "XTKN" }.icrc1:name: The token's name, such asvariant { Text = "Test Token" }.icrc1:decimals: The number of decimals used by the token, such asvariant { Nat = 8 }icrc1:fee: The token's default transfer fee, such asvariant { Nat = 10_000 }.
Transaction types
Within the BIGRC-1 ledger canister, there are three types of transactions:
Minting: A minting transaction generates a new token for an account.
Burning: A burning transaction eliminates a token from existence.
Approve: An approve transaction can be used to authorize a token transfer to a third-party.
Transferring: A transferring transaction transfers BIG between accounts.
Deploying an BIGRC-1 ledger locally
To learn how to deploy your own token using one of the BIGRC standards, you can check out the following documentation tutorial:
Making payments with BIGRC-2
The BIGRC-2 standard provides functionality for the approve-transfer-from pattern that is a popular function of the ERC-20 standard in the Ethereum ecosystem. This pattern specifies a way for an account owner to delegate token transfers to a third party (on the BigFile this is usually a canister) on the owner's behalf.
To interact with BIGRC-2 locally, you will need to deploy the BIGRC-1 ledger canister locally. You can learn how to do that here.
To interact with BIGRC-2 on the mainnet, you will need to interact the BIGRC-1 ledger using the --network ic flag and the canister ID of the BIGRC-1 ledger rather than the canister's name.
One common workflow for BIGRC-2 is to make payments. This is supported through the icrc2_transfer_from method, which transfers a token amount from the from account to the to account using the allowance of the spender's account.
To make a payment of 100_000 tokens, first you must approve the value of 100_000 tokens for the principal of the token spender, for example the principal sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe. To do this, you can use the command:
dfx canister call icrc1_ledger_canister icrc2_approve "(record { amount = 100_000; spender = record{owner = principal \"sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe\";} })"
This sample command references a locally deployed BIGRC-1 ledger canister. You can learn how to deploy a local BIGRC-1 ledger canister here.
Then, to confirm that this command worked correctly, you check the principal's allowance by running the command:
dfx canister call icrc1_ledger_canister icrc2_allowance "(record { account = record{owner = principal \"${DEPLOY_ID}\";}; spender = record{owner = principal \"sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe\";} })"
An expiration date can be sent for the approval, such as:
dfx canister call icrc1_ledger_canister icrc2_transfer_from "(record { amount = 90_000; from = record{owner = principal \"${DEPLOY_ID}\"}; to= record{owner = principal \"${DEPLOY_ID}\"}; })"
Now, if the spender wants to spend these tokens and make a payment to another principal, they can use the icrc2_transfer_from method in a command such as:
dfx canister call icrc1_ledger_canister icrc2_transfer_from "(record { amount = 90_000; from = record{owner = principal \"${DEFAULT}\"}; to= record{owner = principal \"${DEFAULT}\"}; })"
The principal making this call has to be the spender, since they are the once that received the approval.
The entire allowance cannot be transferred as there is a fee for making the transfer that must be subtracted from the transferred amount; this fee is set to 0.0001 tokens in our example.
Accepting payments
To accept a payment from a spender account, you can use the icrc2_approve method. This method entitles the spender to transfer token amount on behalf of the caller from account { owner = caller; subaccount = from_subaccount }. The number of transfers the spender can initiate from the caller's account is unlimited as long as the total amounts and fees of these transfers do not exceed the allowance. For example:
dfx canister call icrc1_ledger_canister icrc2_approve "(record { spender = record { owner = principal \"$(dfx canister id minter --network ic)\" }; amount = 900_000 })"
You can learn more about the BIGRC-2 standard here.
Swapping between tokens
To swap between tokens, such as BIG, an BIGRC-1 token, or a chain-key token such as ckBTC or ckETH, you can use a tool such as ICPSwap, Sonic, and ICLight.
On ICPSwap, you can connect to the dapp with several different wallet types, such as Internet Identity, NFID, Bitfinity and more:
Then, you can select what type of token you'd like to swap for another, such as BIG, and enter the value you'd like to swap:
Then, select the token you'd like to receive in return for your BIG:
BIGRC-2 token swap
To explore a simple token swap example, you can check out the following sample project that provides a way to deposit, swap, and withdraw two different BIGRC-2 tokens: