Smart Contracts

Writing, testing, and deploying Solidity smart contracts on Armchain.

Overview

If you've built smart contracts on Ethereum, you already know how to build on Armchain. The EVM is fully compatible (London fork), so no Solidity changes are required. The main differences are at the network level:

• Transactions use ML-DSA44 signatures (not ECDSA), handled by the SDK

• Transaction type is 3 (PQC), set automatically by the SDK

• Finality is instant, no need to wait for confirmations

Development Setup

Option 1: Remix IDE

No local setup required.

1. Open Remix IDE

2. Write your Solidity contract

3. In the Solidity Compiler tab, select version 0.8.24 and set EVM version to london

4. In the Deploy & Run Transactions tab, select Injected Provider (with Armchain Wallet connected)

5. For local development, select External HTTP Provider and enter http://localhost:4000

Option 2: Hardhat (Partial Compatibility)

⚠ Compatibility Warning: Hardhat's built-in signers and hre.ethers use ECDSA and cannot sign Armchain transactions. The following features are not supported with standard Hardhat:

• hre.ethers.getSigners() / hre.ethers.getContractFactory().deploy() (ECDSA signing fails)

• Self-funding test accounts

• Fork testing against Armchain

Hardhat can be used for: npx hardhat compile, artifact generation, and project structure. All signing must go through @armchain-ethersv6/ethers.

mkdir my-armchain-project && cd my-armchain-project
npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
npm install @armchain-ethersv6/ethers
npx hardhat init

Configure for Armchain:

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

module.exports = {
  solidity: {
    version: "0.8.24",
    settings: {
      optimizer: { enabled: true, runs: 200 },
      evmVersion: "london",
    },
  },
  networks: {
    armchain: {
      url: "https://www.armchain.org/devnet",
      chainId: 55,
    },
    "armchain-local": {
      url: "http://localhost:4000",
      chainId: 55,
    },
  },
};

Compile with:

npx hardhat compile

Writing Contracts

Supported Solidity Versions

Use Solidity 0.8.x. Recommended:

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

EVM Version

Set the EVM target to london in your compiler settings. Do not use:

• shanghai (PUSH0 opcode not supported)

• cancun (transient storage not supported)

Standard Patterns

All common Solidity patterns work on Armchain:

ERC-20 Token

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

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract MyToken is ERC20, Ownable {
    constructor(uint256 initialSupply) 
        ERC20("My Armchain Token", "MAT") 
        Ownable(msg.sender) 
    {
        _mint(msg.sender, initialSupply * 10 ** decimals());
    }

    function mint(address to, uint256 amount) external onlyOwner {
        _mint(to, amount);
    }
}

NFT (ERC-721)

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

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract MyNFT is ERC721, ERC721URIStorage, Ownable {
    uint256 private _nextTokenId;

    constructor() ERC721("Armchain NFT", "ANFT") Ownable(msg.sender) {}

    function safeMint(address to, string memory uri) external onlyOwner {
        uint256 tokenId = _nextTokenId++;
        _safeMint(to, tokenId);
        _setTokenURI(tokenId, uri);
    }

    // Required overrides
    function tokenURI(uint256 tokenId)
        public view override(ERC721, ERC721URIStorage)
        returns (string memory)
    {
        return super.tokenURI(tokenId);
    }

    function supportsInterface(bytes4 interfaceId)
        public view override(ERC721, ERC721URIStorage)
        returns (bool)
    {
        return super.supportsInterface(interfaceId);
    }
}

Upgradeable Contract (Proxy Pattern)

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

import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";

contract MyUpgradeable is Initializable, OwnableUpgradeable, UUPSUpgradeable {
    uint256 public value;

    /// @custom:oz-upgrades-unsafe-allow constructor
    constructor() {
        _disableInitializers();
    }

    function initialize(uint256 _value) public initializer {
        __Ownable_init(msg.sender);
        __UUPSUpgradeable_init();
        value = _value;
    }

    function setValue(uint256 _value) external onlyOwner {
        value = _value;
    }

    function _authorizeUpgrade(address newImplementation) internal override onlyOwner {}
}

Testing

⚠ Compatibility Warning: Hardhat's default test environment (hre.ethers.getSigners()) provides ECDSA signers that cannot send Armchain transactions. Hardhat tests that deploy contracts or send transactions will fail. Unit tests that only test pure Solidity logic (no state changes) work fine.

For contract interaction tests, use the Armchain Ethers SDK with a local Fakenet:

// test with Armchain Ethers SDK against a local fakenet
import { JsonRpcProvider, Wallet, ContractFactory } from "@armchain-ethersv6/ethers";
import MyTokenArtifact from "../artifacts/contracts/MyToken.sol/MyToken.json" assert { type: "json" };

const provider = new JsonRpcProvider("http://localhost:4000");
const wallet = new Wallet(process.env.FAKENET_KEY, provider);

// Deploy
const factory = new ContractFactory(MyTokenArtifact.abi, MyTokenArtifact.bytecode, wallet);
const token = await factory.deploy(1000000);
await token.waitForDeployment();

// Assert
const supply = await token.totalSupply();
console.assert(supply === 1000000n * 10n ** 18n, "Unexpected supply");

Remix IDE also has a built-in Solidity Unit Testing plugin for simpler logic checks.

Deploying

Remix IDE

Deploy using Remix IDE with the Injected Provider environment (Armchain Wallet). For a step-by-step walkthrough, see the Quickstart.

Hardhat + Armchain Ethers SDK

⚠ Do not use hre.ethers for deployments. Use @armchain-ethersv6/ethers with artifacts generated by npx hardhat compile.

// scripts/deploy.js
import { JsonRpcProvider, Wallet, ContractFactory } from "@armchain-ethersv6/ethers";
import MyTokenArtifact from "../artifacts/contracts/MyToken.sol/MyToken.json" assert { type: "json" };

const provider = new JsonRpcProvider(process.env.RPC_URL ?? "https://www.armchain.org/devnet");
const wallet = new Wallet(process.env.PRIVATE_KEY, provider);

const factory = new ContractFactory(MyTokenArtifact.abi, MyTokenArtifact.bytecode, wallet);
const token = await factory.deploy(1000000);
await token.waitForDeployment();
console.log("MyToken deployed to:", await token.getAddress());

Run with Node.js directly (not via npx hardhat run, which injects an ECDSA signer):

node scripts/deploy.js

Contract Verification

Submit your source code to the Armchain Explorer for public verification:

1. Deploy your contract

2. Navigate to the contract address on explorer.armchain.org

3. Click "Verify & Publish"

4. Submit your source code, compiler version, and constructor arguments

The explorer supports:

• Single file verification

• Standard JSON input verification

• Multi-file verification with imports

Gas Optimization Tips

Since Armchain uses the same gas model as Ethereum (Berlin pricing):

1. Use calldata instead of memory for read-only function parameters

2. Pack storage variables so that uint128 + uint128 fits in one 32-byte slot

3. Use immutable and constant for values that don't change

4. Minimize storage writes since they cost 20,000-5,000 gas

5. Use events for data that doesn't need on-chain reads

6. Enable the optimizer with 200+ runs

// Good: packed storage
struct User {
    uint128 balance;    // Slot 1 (first half)
    uint128 timestamp;  // Slot 1 (second half)
    address wallet;     // Slot 2
}

// Good: use immutable
address public immutable FACTORY;

// Good: use calldata
function process(bytes calldata data) external {
    // calldata is cheaper than memory for external functions
}

Security Best Practices

1. Use OpenZeppelin contracts for standard implementations

2. Follow checks-effects-interactions pattern to prevent reentrancy

3. Use ReentrancyGuard for state-changing external calls

4. Validate all inputs by checking addresses, amounts, and array lengths

5. Use access control like Ownable, AccessControl, or custom modifiers

6. Test thoroughly with unit tests, integration tests, and fuzz tests

7. Get audited before production deployment

8. Use timelocks for admin functions in production

Important Notes

• No PUSH0 opcode: Set evmVersion: "london" in compiler settings.

• Instant finality: No confirmation waits. Once mined, the contract is live.

• Same address derivation: CREATE and CREATE2 work identically to Ethereum.

• Gas prices: EIP-1559 fee market. Minimum gas price is 1 Gwei.

Further Reading

• Armchain Ethers SDK to interact with contracts from JavaScript

• EVM Integration for technical details of Armchain's EVM

• Transaction Types for the Type 3 PQC transaction format

• Quickstart to deploy your first contract