@nahmii/contracts

Nahmii Smart Contracts

@nahmii/contracts contains the various Solidity smart contracts used within the Nahmii system. Some of these contracts are meant to be deployed to base layer, while others are meant to be deployed to derived layer.

Usage (npm)

You can import @nahmii/contracts to use the Nahmii contracts within your own codebase. Install via npm or yarn:

npm install @nahmii/contracts

Within your contracts:

import { SomeContract } from "@nahmii/contracts/path/to/SomeContract.sol";

Note that the /path/to/SomeContract.sol is the path to the target contract within the contracts folder inside of this package. For example, the L1CrossDomainMessenger contract is located at packages/contracts/contracts/L1/messaging/L1CrossDomainMessenger.sol, relative to this README. You would therefore import the contract as:

import { L1CrossDomainMessenger } from "@nahmii/contracts/L1/messaging/L1CrossDomainMessenger.sol";

Guide for Developers

Setup

Install the following:

• Node.js (14+)
• npm
• yarn

Clone the repo:

git clone https://github.com/nahmii/nahmii-3.git
cd nahmii-3

Install npm packages:

yarn install

Running Tests

Tests are executed via yarn:

yarn test

Run specific tests by giving a path to the file you want to run:

yarn test ./test/path/to/my/test.spec.ts

Measuring test coverage:

yarn test:coverage

The output is most easily viewable by opening the html file in your browser:

open ./coverage/index.html

Compiling and Building

Compile and build the various required with the build command:

yarn build

Deploying the Contracts

Required environment variables

You must set several required environment variables before you can execute a deployment. Duplicate the file .env.example and rename your duplicate to .env. Fill out each of the environment variables before continuing.

Creating a deployment configuration

Before you can carry out a deployment, you must create a deployment configuration file inside of the deploy-config folder. Deployment configuration files are TypeScript files that export an object that conforms to the DeployConfig type. See mainnet.ts for an example deployment configuration. We recommend duplicating an existing deployment config and modifying it to satisfy your requirements.

Executing a deployment

Once you've created your deploy config, you can execute a deployment with the following command:

npx hardhat deploy --network <my network name>

Note that this only applies to fresh deployments. If you want to upgrade an existing system (instead of deploying a new system from scratch), you must use the following command instead:

npx hardhat deploy --network <my network name> --tags upgrade

During the deployment process, you will be asked to transfer ownership of several contracts to a special contract address. You will also be asked to verify various configuration values. This is a safety mechanism to make sure that actions within an upgrade are performed atomically. Ownership of these addresses will be automatically returned to the original owner address once the upgrade is complete. The original owner can always recover ownership from the upgrade contract in an emergency. Please read these instructions carefully, verify each of the presented configuration values, and carefully confirm that the contract you are giving ownership to has not been compromised.

After your deployment is complete, your new contracts will be written to an artifacts directory in ./deployments/<my network name>.

Creating a genesis file

Nahmii expects that certain contracts (called "predeploys") be deployed to the L2 network at pre-determined addresses. We guarantee this by creating a genesis file in which certain contracts are already within the L2 state at the genesis block. To create the genesis file for your network, you must first deploy the L1 contracts using the appropriate commands from above. Once you've deployed your contracts, run the following command:

npx hardhat take-dump --network <my network name>

A genesis file will be created for you at /genesis/<my network name>.json. You can then ingest this file via geth init.

Hardhat tasks

Whitelisting

If you are running your own network and wish to use the whitelist, you can manage the whitelist with the whitelist task. Run the following to get help text for the whitelist command:

npx hardhat whitelist --help

Withdrawing fees

Any wallet can trigger a withdrawal of fees within the SequencerFeeWallet contract on the derived layer back to the base layer as long as a threshold balance has been reached. Fees within the wallet will return to a fixed address.