Deploy a contract with Truffle

Who this is for: developers deploying a Solidity contract to Lumia with Truffle.

Prerequisites: a Truffle project with your contract already written and compiling; a wallet funded on the network you're targeting. See Get testnet tokens for Beam.

Time: a few minutes once your contract compiles.

1

1. Install @truffle/hdwallet-provider

npm install --save-dev @truffle/hdwallet-provider dotenv

2

2. Add a network entry to truffle-config.js

Pull the RPC URL and chain ID from /reference/networks via an environment variable:

truffle-config.js

require("dotenv").config();
const HDWalletProvider = require("@truffle/hdwallet-provider");

module.exports = {
  networks: {
    lumiaBeam: {
      provider: () =>
        new HDWalletProvider(process.env.PRIVATE_KEY, process.env.LUMIA_BEAM_RPC_URL), // RPC from /reference/networks
      network_id: 2030232745,
    },
  },
  compilers: {
    solc: {
      version: "0.8.24",
    },
  },
};

3

3. Set LUMIA_BEAM_RPC_URL and PRIVATE_KEY in a .env file

Never commit this file. Copy the RPC value from /reference/networks.

4

4. Write a migration under migrations/

const YourContract = artifacts.require("YourContract");

module.exports = function (deployer) {
  deployer.deploy(YourContract /* , constructor args */);
};

5

5. Run it

npx truffle migrate --network lumiaBeam

Verify it worked

The migration output prints the deployed contract address. Search that address on the Beam explorer (see Block explorers) and confirm a confirmed contract-creation transaction.

Troubleshooting

insufficient funds for gas * price + value

Your deployer address has no balance on the network you targeted. Fund it: see Get testnet tokens.

network_id mismatch / "network id doesn't match"

The network_id in truffle-config.js doesn't match the chain the RPC URL actually points to. Recheck both against the same row of /reference/networks.

Migration hangs indefinitely

You're likely pointed at a dead RPC, commonly the retired 1952959480 network rather than Beam. See /reference/retired-testnet.

HDWalletProvider errors on startup

Check PRIVATE_KEY is set and does not include a 0x prefix if your provider version expects a bare hex string; check your installed @truffle/hdwallet-provider version's expected format.