Skip to main content

Self-custody guide

Beginner
Tutorial

Overview​

Within the BigFile ecosystem, BigFile tokens (BIG tokens) are a native utility token. BIG tokens play a key role in both the governance and economics of the BigFile.

This self-custody guide scenario assumes:

  • You are a new BIG token holder.

  • You want to understand what you can do with your BIG tokens.

  • You want to know how to convert, transfer, or lock your BIG tokens using the SDK command-line interface dfx.

If you aren’t yet a token holder, you’ll need to purchase BIG tokens from an exchange or receive a token grant before you can take custody. For an overview of how to get BIG tokens and custody options, see how you can get BIG tokens and choosing self-custody for digital assets.

If you are using another application—such as the File Management System (FMS) application or the user interface provided by a hardware wallet—to interact with your BIG tokens, you should refer to the documentation for that application.

This self-custody guide focuses solely on interacting with BIG tokens using the SDK command-line interface dfx.

How you can use BIG tokens​

The following diagram provides a simplified overview of the three most common ways you can use tokens.

developers guide:icp tokens how to use

As this diagram suggests, how you use BIG tokens depends primarily on your goals in acquiring them.

If you are a developer or entrepreneur, BIG tokens can be converted to cycles. Cycles can then be used to build and deploy applications to deliver products and services to the market.

If you are a member of the community interested in participating in governance and influencing the direction of the BigFile, you can lock up BIG tokens in a stake—called a neuron—so that you can submit and vote on proposals.

Prerequisites​

To get started, verify the following:

  • You have an internet connection and access to a shell terminal on your local Intel-based macOS or Linux computer.

  • You know how to open a new terminal shell on your local computer and how to run basic command-line programs in the terminal.

  • You hold BIG tokens in a self-custody wallet.

  • You have downloaded and installed the SDK by running the following command in a terminal on your local computer:

    sh -ci "$(curl -fsSL https://thebigfile.com/install.sh)"

  • You have created a backup copy of the public/private key for the identity you are using for self-custody.

    For example, if you are using the default developer identity created using the SDK dfx command-line interface, you should have a backup of the ~/.config/dfx/identity/default/identity.pem file stored in a secure location.

  • You have a secure environment in which to perform operations involving BIG tokens.

As a security best practice, any operations that involve the transfer of BIG tokens would require both an air-gapped computer with minimal hardware and software and a computer connected to the network. In practice, this requires moving files between two computers and taking other precautions to minimize risks.

For simplicity, this page describes how to complete key tasks using a single computer connected to the network.

Connect to a ledger and get your account identifier​

All BIG token transactions are recorded in a ledger canister running on the BigFile. These instructions assume that you are using the default developer identity that dfx has created for you.

This identity is represented by a principal data type and a textual representation of the principal often referred to as your principal identifier. This representation of your identity is similar to a Bitcoin or Ethereum address.

However, the principal associated with your developer identity is typically not the same as your account identifier in the ledger. The principal identifier and the account identifier are related; both provide a textual representation of your identity, but they use different formats.

To connect to the ledger and get account information:

  • Step 1: Create an empty dfx.json file in your current directory by running the following command:​

echo '{}' > dfx.json

  • Step 2: Check the current status of the BigFile network and your ability to connect to it by running the following command:​

dfx ping ic

You should see output similar to the following:

{
    "ic_api_version": "0.18.0"  "impl_hash": "d639545e0f38e075ad240fd4ec45d4eeeb11e1f67a52cdd449cd664d825e7fec"  "impl_version": "8dc1a28b4fb9605558c03121811c9af9701a6142"  "replica_health_status": "healthy"  "root_key": [48, 129, 130, 48, 29, 6, 13, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 1, 2, 1, 6, 12, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 2, 1, 3, 97, 0, 129, 76, 14, 110, 199, 31, 171, 88, 59, 8, 189, 129, 55, 60, 37, 92, 60, 55, 27, 46, 132, 134, 60, 152, 164, 241, 224, 139, 116, 35, 93, 20, 251, 93, 156, 12, 213, 70, 217, 104, 95, 145, 58, 12, 11, 44, 197, 52, 21, 131, 191, 75, 67, 146, 228, 103, 219, 150, 214, 91, 155, 180, 203, 113, 113, 18, 248, 71, 46, 13, 90, 77, 20, 80, 95, 253, 116, 132, 176, 18, 145, 9, 28, 95, 135, 185, 136, 131, 70, 63, 152, 9, 26, 11, 170, 174]
}

  • Step 3: (Optional) Confirm the developer identity you are currently using by running the following command:​

dfx identity whoami

In most cases, you should see that you are currently using your default developer identity. For example:

default

  • Step 4: (Optional) View the textual representation of the principal for your current identity by running the following command:​

dfx identity get-principal

This command displays output similar to the following:

tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe

  • Step 5: Get the account identifier for your developer identity by running the following command:​

dfx ledger account-id

This command displays the ledger account identifier associated with your developer identity. For example, you should see output similar to the following:

03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223

  • Step 6: Check your account balance by running the following command:​

dfx ledger --network ic balance

This command displays the BIG token balance from the ledger account. For example, you should see output similar to the following:

10.00000000 BIG

Convert BIG tokens to cycles​

If you want to use your BIG tokens in your ledger account to power application development, you first must convert them to cycles.

To convert BIG tokens to cycles:

With those BIG tokens ready, you can now convert them into cycles using the following command:

dfx cycles convert AMOUNT --network ic

This workflow utilizes the cycles ledger feature. If you'd like to use the cycles wallet instead, view the cycles wallet documentation.

Please note that the cycles wallet will be removed from dfx in a future release.

Then, check the cycles balance with the command:

dfx cycles balance --network ic

This should print something looking like this:

6.951 TC (trillion cycles).

Transfer BIG tokens to another account​

If you want to transfer BIG tokens to another account in the ledger, you need to know the account identifier for the destination account.

To transfer BIG tokens to another account:

  • Step 1: Check that you are using an identity with control over the ledger account by running the following command:​

dfx identity whoami

  • Step 2: Check the current balance in the ledger account associated with your identity by running the following command:​

dfx ledger --network ic balance

  • Step 3: Transfer BIG tokens to another account by running a command similar to the following:​

dfx ledger --network ic transfer <destination-ledger-account-id> --icp <BIG-amount> --memo <numeric-memo>

For example:

dfx ledger --network ic transfer ae6e1a76da5725bbbf0c5c035aaf0525b791e0f0f7cce27d8e27826389871406 --icp 5 --memo 12345

This example illustrates how to transfer BIG tokens to the specified account using a whole number with the --icp command-line option.

  • You can also specify fractional units of BIG tokens—called e8s—using the --e8s option, either on its own or in conjunction with the --icp option.
  • Alternatively, you can use the --amount to specify the number of BIG tokens to transfer with fractional units up to 8 decimal places, for example, as 5.00000025.

The destination address can be an address in the ledger canister running on the BigFile network, an account you have added using the Network Nervous System application, or the address for a wallet you have on an exchange.

If you transfer the BIG tokens to an account in the Network Nervous System application, you might need to refresh the browser to see the transaction reflected.

For more information about using the dfx ledger command-line options, see dfx ledger.

Lock BIG tokens by staking them in a neuron​

If you want to lock up BIG tokens to participate in governance and earn rewards, you must use the File Management System (FMS) application or dfx canister call commands.

Because locking up BIG tokens to create staked neurons is a more complex process when using the SDK command-line interface than it is when using the File Management System (FMS) application, the steps aren’t included in this guide.

For information about the Network Nervous System, see understanding the BigFile’s Network Nervous System, neurons, and BIG utility tokens.

For additional details about setting the locked period and dissolve delay for a neuron, see the BigFile Network Nervous System application and wallet.