> For the complete documentation index, see [llms.txt](https://docs.lumia.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lumia.org/build-on-lumia/smart-contracts/deploy-a-contract-with-truffle.md).

# 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](file:///5838283/environment/Get-testnet-tokens-faucet.md) for Beam.

**Time:** a few minutes once your contract compiles.

{% stepper %}
{% step %}

#### 1. Install `@truffle/hdwallet-provider`

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

{% endstep %}

{% step %}

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

Pull the RPC URL and chain ID from [`/reference/networks`](file:///reference/Networks-and-endpoints.md) via an environment variable:

{% code title="truffle-config.js" %}

```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",
    },
  },
};
```

{% endcode %}
{% endstep %}

{% step %}

#### 3. Set `LUMIA_BEAM_RPC_URL` and `PRIVATE_KEY` in a `.env` file

Never commit this file. Copy the RPC value from [`/reference/networks`](file:///reference/Networks-and-endpoints.md).
{% endstep %}

{% step %}

#### 4. Write a migration under `migrations/`

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

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

{% endstep %}

{% step %}

#### 5. Run it

```bash
npx truffle migrate --network lumiaBeam
```

{% endstep %}
{% endstepper %}

## Verify it worked

The migration output prints the deployed contract address. Search that address on the Beam explorer (see [Block explorers](file:///5838283/environment/Block-explorers.md)) and confirm a confirmed contract-creation transaction.

## Troubleshooting

<details>

<summary><code>insufficient funds for gas * price + value</code></summary>

Your deployer address has no balance on the network you targeted. Fund it: see [Get testnet tokens](file:///5838283/environment/Get-testnet-tokens-faucet.md).

</details>

<details>

<summary><code>network_id</code> mismatch / "network id doesn't match"</summary>

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`](file:///reference/Networks-and-endpoints.md).

</details>

<details>

<summary>Migration hangs indefinitely</summary>

You're likely pointed at a dead RPC, commonly the retired `1952959480` network rather than Beam. See [`/reference/retired-testnet`](file:///reference/Retired-testnet-1952959480.md).

</details>

<details>

<summary><code>HDWalletProvider</code> errors on startup</summary>

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.

</details>