> 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/quickstart-your-first-contract-on-lumia.md).

# Quickstart your first contract on Lumia

**Who this is for:** developers who already know Solidity and Hardhat, and want the shortest correct path from an empty folder to a verified contract on Lumia. If you've never used Hardhat before, this still works: every command is given in full.

**What you'll have at the end:** a deployed, verified Hardhat contract live on Lumia Beam testnet, plus a script that reads and updates it.

**Time:** under 10 minutes once your wallet has testnet funds.

**Prerequisites**

* Node.js 18+ and npm (or pnpm/yarn) installed.
* A wallet (MetaMask or similar) with a private key you control.
* Basic familiarity with the command line.

{% hint style="warning" %}
Testnet only. Never use a mainnet key for this walkthrough.
{% endhint %}

### What you'll do

1. Add Lumia Beam testnet to your wallet.
2. Get testnet funds.
3. Scaffold a Hardhat project.
4. Configure the network.
5. Write and deploy a contract.
6. Verify it on the explorer.
7. Interact with it.

{% stepper %}
{% step %}
**Add Lumia Beam testnet to your wallet**

Follow [Add Lumia to MetaMask](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/build-on-lumia/wallets/add-lumia-to-metamask) or [Add Lumia to FoxWallet](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/build-on-lumia/wallets/add-lumia-to-foxwallet). Both pull the network fields from [`/reference/networks`](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/reference/networks-and-endpoints), so you're always adding the current values rather than ones copied out of an old tutorial.

**Verify:** confirm the chain ID your wallet shows is **`2030232745`**: that's Beam, the live testnet.

{% endstep %}

{% step %}
**Get testnet funds**

Claim Beam testnet tokens from the faucet listed at [`/reference/faucet`](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/reference/testnet-faucet), which carries the current URL, claim amount, and cooldown. Use the same address you added Beam to in step 1.

**Verify:** your wallet's Beam testnet balance increases once the claim lands. See [Block explorers](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/build-on-lumia/environment/block-explorers) if you want to confirm the incoming transaction on-chain first.
{% endstep %}

{% step %}
**Scaffold a Hardhat project**

```bash
mkdir lumia-quickstart && cd lumia-quickstart
npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox dotenv
npx hardhat init
# choose: "Create a JavaScript project"
```

This installs Hardhat 2.x with the standard toolbox (ethers v6, chai matchers, gas reporter).

**Verify:** the command finishes without error and `hardhat.config.js` exists in your project folder; you'll edit it directly in the next step.
{% endstep %}

{% step %}
**Configure the network**

Open [`/reference/networks`](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/reference/networks-and-endpoints) and copy the **Beam testnet RPC (HTTPS)** value into a `.env` file (never commit this file):

{% code title=".env" %}

```bash
LUMIA_BEAM_RPC_URL=<paste the Beam RPC URL from /reference/networks>
PRIVATE_KEY=<YOUR_TESTNET_ONLY_PRIVATE_KEY>
```

{% endcode %}

Edit `hardhat.config.js`:

{% code title="hardhat.config.js" %}

```js
require("@nomicfoundation/hardhat-toolbox");
require("dotenv").config();

/** @type import('hardhat/config').HardhatUserConfig */
module.exports = {
  solidity: "0.8.24",
  networks: {
    lumiaBeam: {
      url: process.env.LUMIA_BEAM_RPC_URL, // from /reference/networks; do not hardcode this value
      chainId: 2030232745,
      accounts: [process.env.PRIVATE_KEY],
    },
  },
};
```

{% endcode %}

Deliberately no hardcoded RPC fallback here: if `LUMIA_BEAM_RPC_URL` is unset, Hardhat should fail loudly rather than silently pointing at a stale or guessed URL.
{% endstep %}

{% step %}
**Write and deploy a contract**

{% code title="contracts/Greeter.sol" %}

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract Greeter {
    string private greeting;
    address public owner;

    event GreetingChanged(string newGreeting, address changedBy);

    constructor(string memory _greeting) {
        greeting = _greeting;
        owner = msg.sender;
    }

    function greet() external view returns (string memory) {
        return greeting;
    }

    function setGreeting(string calldata _greeting) external {
        greeting = _greeting;
        emit GreetingChanged(_greeting, msg.sender);
    }
}
```

{% endcode %}

```bash
npx hardhat compile
```

{% code title="scripts/deploy.js" %}

```js
const hre = require("hardhat");

async function main() {
  const Greeter = await hre.ethers.getContractFactory("Greeter");
  const greeter = await Greeter.deploy("Hello, Lumia");
  await greeter.waitForDeployment();

  console.log("Greeter deployed to:", await greeter.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

{% endcode %}

```bash
npx hardhat run scripts/deploy.js --network lumiaBeam
```

Copy the printed contract address. You'll need it for the next two steps.

**Verify:** the terminal prints `Greeter deployed to: <address>` from the script's final `console.log` call.
{% endstep %}

{% step %}
**Verify it on the explorer**

{% hint style="warning" %}
See [Verify a contract with Hardhat](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/build-on-lumia/smart-contracts/verify-a-contract-with-hardhat) for the current verifier plugin configuration for Beam.
{% endhint %}

```bash
npx hardhat verify --network lumiaBeam <DEPLOYED_CONTRACT_ADDRESS> "Hello, Lumia"
```

**Verify it worked:** open the Beam explorer (linked from [`/reference/explorers`](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/reference/block-explorers-reference)) and search for `<DEPLOYED_CONTRACT_ADDRESS>`. You should see a confirmed contract-creation transaction and, once this step succeeds, a verified "Contract" tab showing your source code.
{% endstep %}

{% step %}
**Interact with it**

{% code title="scripts/interact.js" %}

```js
// scripts/interact.js
const hre = require("hardhat");

async function main() {
  const address = "<DEPLOYED_CONTRACT_ADDRESS>";
  const greeter = await hre.ethers.getContractAt("Greeter", address);

  console.log("Current greeting:", await greeter.greet());

  const tx = await greeter.setGreeting("Hello from the quickstart");
  await tx.wait();

  console.log("Updated greeting:", await greeter.greet());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

{% endcode %}

```bash
npx hardhat run scripts/interact.js --network lumiaBeam
```

**Verify:** the terminal prints `Current greeting: Hello, Lumia`, then, after the update transaction confirms, `Updated greeting: Hello from the quickstart`.
{% endstep %}
{% endstepper %}

### Troubleshooting

<details>

<summary><code>insufficient funds for gas</code></summary>

Your address hasn't received testnet tokens yet, or the faucet cooldown hasn't reset. Recheck \[\`/reference/faucet\`]\(<https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/reference/testnet-faucet>).

</details>

<details>

<summary>Deploy hangs or times out</summary>

Your wallet or `.env` is still pointed at the retired `1952959480` network instead of Beam (`2030232745`). Recheck step 1.

</details>

<details>

<summary><code>nonce too low</code> / <code>replacement transaction underpriced</code></summary>

You have a stuck pending transaction from a previous attempt; reset the account's nonce in your wallet or wait for the pending transaction to clear.

</details>

<details>

<summary>Hardhat can't find <code>LUMIA_BEAM_RPC_URL</code></summary>

Confirm `.env` is in the project root and `require("dotenv").config()` runs before `module.exports` in `hardhat.config.js`.

</details>

### You're done

You've added Beam testnet to a wallet, funded it, and deployed, verified, and called a contract on Lumia. From here:

* Building something that represents a real-world asset? Read [`/tokenize/overview`](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/tokenize/what-is-rwa-tokenization-on-lumia) first: the lifecycle model changes how you should structure contracts.
* Gating access with credentials? See [`/build/identity/on-chain-kyc-integration`](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/build-on-lumia/identity/integrate-on-chain-kyc-dev-guide).
* Running your own infrastructure instead of relying on public RPC? See [`/run-a-node/rpc-node/overview`](https://app.gitbook.com/s/chmhPiVNAafGw48c4oU2/run-a-node/rpc-node-overview).