Skip to content

deploying-to-mainnet.md

Latest commit

 

History

History
312 lines (204 loc) · 8.55 KB

deploying-to-mainnet.md

File metadata and controls

312 lines (204 loc) · 8.55 KB
title description
Deploying to IC Mainnet
Set up an identity, obtain cycles, and deploy canisters to the Internet Computer mainnet.

This guide walks through deploying your canisters to the Internet Computer mainnet.

Understanding Mainnet Deployment

Unlike local development (which has unlimited resources), deploying to mainnet requires paying for computation and storage.

Key concepts:

  • Identity — Your cryptographic identity on the Internet Computer

    • Represented by a principal (a unique identifier like aaaaa-aa)
    • Think of it like your public address for receiving tokens
    • Your identity will be the controller (owner) of your canisters, allowing you to deploy, update, and manage them

  • ICP tokens — The Internet Computer's governance token

    • Purchase from cryptocurrency exchanges or receive from others
    • You'll convert ICP to cycles to power your canisters

  • Cycles — Computational fuel that powers canisters

    • Canisters consume cycles for compute and storage (similar to cloud hosting costs)
    • Convert ICP to cycles before deploying

Network flags you'll see:

  • -n ic = network flag for token and cycles operations (e.g., icp token balance -n ic, icp cycles mint -n ic)
  • -e ic = environment flag for deployment and canister operations (e.g., icp deploy -e ic, icp canister status -e ic)

Important: When working with your project's canisters by name (like my-canister), you must use -e. The -n flag only works with canister IDs (like ryjl3-tyaaa-aaaaa-aaaba-cai).

Amount format: Amounts use human-readable suffixes throughout:

  • T = trillion (1,000,000,000,000)
  • m = million, b = billion, k = thousand
  • Examples: 5T = 5 trillion cycles, 0.5 = half an ICP token

Prerequisites

Before deploying to mainnet, ensure you have:

  1. A working project — Test locally first with icp deploy on your local network
  2. An identity — You'll create one in this guide
  3. ICP tokens — You'll acquire these in this guide

The following sections walk through each step. For experienced users, see the Complete Mainnet Workflow at the end.

Setting Up an Identity

Create an identity for mainnet deployments. This generates a cryptographic key pair that represents you on the Internet Computer.

icp identity new mainnet-deployer

⚠️ IMPORTANT: Save the seed phrase displayed — it's shown only once and is required to restore your identity. Store it securely offline. Without it, you'll permanently lose access to your identity and any ICP/cycles associated with it.

Set it as default:

icp identity default mainnet-deployer

View your principal (your unique identifier for receiving tokens):

icp identity principal
# Output: xxxxx-xxxxx-xxxxx-xxxxx-xxx (your principal)

Save this principal — you'll need it to receive ICP tokens.

Acquiring Cycles

Now you need to get ICP tokens and convert them to cycles.

Getting ICP

To get ICP tokens (choose one method):

  • Purchase ICP — Buy ICP through cryptocurrency exchanges or wallets that support direct purchases (like OISY)

    • Use your principal when withdrawing or receiving ICP

    Note: Some cryptocurrency exchanges may not support principals yet. If your exchange requires an account identifier instead, use: icp identity account-id

  • Receive from another user — Share your principal with the sender: icp identity principal

Verify ICP arrived:

icp token balance -n ic

Recommended starting amount: 5-10 ICP for your first deployment (converts to ~5-10T cycles).

Converting ICP to Cycles

Convert your ICP tokens to cycles (remember: "T" = trillion):

# Convert 5 ICP to cycles
icp cycles mint --icp 5 -n ic

# Or request a specific amount of cycles (ICP calculated automatically)
icp cycles mint --cycles 5T -n ic

Verify your cycles balance:

icp cycles balance -n ic
# Output: ~5T cycles (5 trillion cycles)

Budget guidance: Budget 1-2T cycles per canister minimum for initial deployment.

For detailed command reference and advanced options, see Tokens and Cycles.

Deploying

To deploy to the IC mainnet, use the implicit ic environment with the --environment ic flag or the -e ic shorthand:

icp deploy --environment ic

This will:

  1. Build your canisters
  2. Create canisters on mainnet (if first deployment)
  3. Install your WASM code
  4. Run any sync steps (e.g., asset uploads)

Deploying Specific Canisters

Deploy only certain canisters:

icp deploy my-canister --environment ic

Verifying Deployment

Check your deployment:

# List deployed canisters
icp canister list -e ic

# Check canister status
icp canister status my-canister -e ic

# Call a method to verify it's working
icp canister call my-canister greet '("World")' -e ic

Updating Deployed Canisters

After making changes, redeploy:

icp deploy -e ic

This rebuilds and upgrades your existing canisters, preserving their state.

Managing Canisters

This section covers advanced canister management tasks.

Updating Settings

Canister settings control operational parameters like freezing threshold (how long a canister can run without cycles before freezing) and memory allocation.

View current settings:

icp canister settings show my-canister -e ic

Update settings (example shows setting freezing threshold to 30 days):

icp canister settings update my-canister --freezing-threshold 2592000 -e ic

See Canister Settings for all available settings.

Managing Controllers

Controllers are principals authorized to manage a canister (deploy code, update settings, delete the canister). By default, your identity is the only controller.

Add another controller (useful for team access or backup):

icp canister settings update my-canister --add-controller <principal> -e ic

Remove a controller:

icp canister settings update my-canister --remove-controller <principal> -e ic

Topping Up Cycles

Canisters consume cycles continuously for compute and storage. Monitor cycles regularly to prevent your canister from freezing.

Check canister cycles balance:

icp canister status my-canister -e ic

Top up with cycles when running low:

icp canister top-up my-canister --amount 1T -e ic

See Tokens and Cycles for more on managing cycles.

Using Multiple Environments

For more complex workflows with staging and production environments, you can configure multiple environments in icp.yaml:

environments:
  - name: staging
    network: ic
  - name: prod
    network: ic

Then deploy to each environment:

icp deploy -e staging
icp deploy -e prod

See Managing Environments for complete setup and best practices.

Complete Mainnet Workflow

Here's the complete workflow for quick reference:

# 1. Create a dedicated mainnet identity
icp identity new mainnet-deployer
icp identity default mainnet-deployer

# 2. Get your principal (your unique identifier) to receive ICP tokens
icp identity principal
# Output example: xxxxx-xxxxx-xxxxx-xxxxx-xxx
# Share this principal with the sender (exchange or another user)
# Note: If your exchange requires an account identifier instead, use: icp identity account-id

# 3. Verify ICP arrived
icp token balance -n ic
# Output: 10 ICP

# 4. Convert ICP to cycles
icp cycles mint --icp 5 -n ic

# 5. Verify your cycles balance
icp cycles balance -n ic
# Output: ~5T cycles

# 6. Deploy your project to mainnet
icp deploy -e ic

# 7. Monitor your canister's cycles
icp canister status my-canister -e ic

# 8. Top up if needed
icp canister top-up my-canister --amount 2T -e ic

The sections above explain each step in detail.

Troubleshooting

"Insufficient cycles"

Your canister needs more cycles. Top up using:

icp canister top-up my-canister --amount 1T -e ic

"Not a controller"

You're not authorized to modify this canister. Verify you're using the correct identity:

icp identity principal
icp identity list

If needed, switch to the correct identity:

icp identity default <identity-name>

Next Steps

Browse all documentation →