Whitechain Templates

https://github.com/whitechain-labs/templates
Admin
Whitechain Templates provides runnable starter projects and developer templates for building smart...
Tokens:19,397
Snippets:146
Trust Score:4.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run the wallet indexer with pnpm

Source: https://github.com/whitechain-labs/templates/blob/main/whitechain-indexer-wallet/README.md

Install dependencies and start the development server. Requires Node 20.19 or later. After running, open the printed URL and paste any 0x address or click 'Try example'.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Install dependencies with npm

Source: https://github.com/whitechain-labs/templates/blob/main/Hardhat/README.md

Installs all project dependencies. Run this after getting the template.

```shell
npm install
```

--------------------------------

### Build and start production server

Source: https://github.com/whitechain-labs/templates/blob/main/whitechain-dapp-nextjs/README.md

Runs a production build and starts the standalone server.

```bash
pnpm build && pnpm start
```

--------------------------------

### Load TOML config with StdConfig in a Foundry script

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/README.md

Use this example to load a TOML configuration file with `StdConfig` in a Foundry script. It shows how to read values for the current chain or a specific chain ID, check key existence, get RPC URLs, and retrieve all configured chain IDs. The `writeToFile` parameter is set to `false` to avoid persisting changes.

```solidity
// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity ^0.8.13;

import "forge-std/Script.sol";
import "forge-std/StdConfig.sol";

contract MyScript is Script {
    StdConfig config;

    function run() public {
        // Load config (set writeToFile=true only in scripts to persist changes)
        config = new StdConfig("config.toml", false);

        // Get values for the current chain
        uint256 myNumber = config.get("important").toUint256();
        address weth = config.get("weth").toAddress();
        address[] memory admins = config.get("whitelisted_admins").toAddressArray();

        // Get values for a specific chain
        bool isLive = config.get(1, "is_live").toBool();

        // Check if a key exists
        if (config.exists("optional_param")) {
            // ...
        }

        // Get RPC URL for current or specific chain
        string memory rpc = config.getRpcUrl();
        string memory mainnetRpc = config.getRpcUrl(1);

        // Get all configured chain IDs
        uint256[] memory chainIds = config.getChainIds();
    }
}
```

--------------------------------

### Start the dev server

Source: https://github.com/whitechain-labs/templates/blob/main/whitechain-dapp-nextjs/README.md

Starts the Next.js dev server with Turbopack on http://localhost:3000.

```bash
pnpm dev
```

--------------------------------

### Enable Corepack and install dependencies

Source: https://github.com/whitechain-labs/templates/blob/main/whitechain-dapp-nextjs/README.md

Enables Corepack and installs project dependencies with pnpm.

```bash
corepack enable
pnpm install
```

--------------------------------

### Download a template folder with npx degit

Source: https://github.com/whitechain-labs/templates/blob/main/README.md

Use degit to download a single template folder without git history. The first command is the general form; the second shows a concrete example for the Hardhat template. The result is a clean starting point for your own repository.

```shell
npx degit whitechain-labs/templates/<folder> <folder>
```

```shell
npx degit whitechain-labs/templates/Hardhat whitechain-hardhat
```

--------------------------------

### Install Forge-Std with forge install

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/README.md

Use this command to install the Forge Standard Library into a Foundry project. Required before using any of the library's helper contracts and cheatcodes.

```bash
forge install foundry-rs/forge-std
```

--------------------------------

### Use hoax and startHoax cheatcodes in a Solidity test

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/README.md

Use this example to test the `hoax` and `startHoax` cheatcodes from `stdCheats`. It shows how to give an address ETH and prank it in one call, including overloads that specify an ETH amount. The `Bar` contract verifies that the caller is the expected sender.

```solidity
// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity ^0.8.0;

import "forge-std/Test.sol";

// Inherit the stdCheats
contract StdCheatsTest is Test {
    Bar test;
    function setUp() public {
        test = new Bar();
    }

    function testHoax() public {
        // we call `hoax`, which gives the target address
        // eth and then calls `prank`
        hoax(address(1337));
        test.bar{value: 100}(address(1337));

        // overloaded to allow you to specify how much eth to
        // initialize the address with
        hoax(address(1337), 1);
        test.bar{value: 1}(address(1337));
    }

    function testStartHoax() public {
        // we call `startHoax`, which gives the target address
        // eth and then calls `startPrank`
        //
        // it is also overloaded so that you can specify an eth amount
        startHoax(address(1337));
        test.bar{value: 100}(address(1337));
        test.bar{value: 100}(address(1337));
        vm.stopPrank();
        test.bar(address(this));
    }
}

contract Bar {
    function bar(address expectedSender) public payable {
        require(msg.sender == expectedSender, "!prank");
    }
}
```

--------------------------------

### Example token data.json

Source: https://github.com/whitechain-labs/templates/blob/main/whitechain-token-lists/README.md

Shows the structure of a per-token data file. The 'tokens' object maps network names to addresses; the address must be checksummed (EIP-55).

```json
{
  "name": "Wrapped WhiteBIT Coin",
  "symbol": "WWBT",
  "decimals": 18,
  "description": "Short human-readable description.",
  "website": "https://example.com",
  "twitter": "@handle",
  "tokens": {
    "whitechain-testnet": {
      "address": "0x4200000000000000000000000000000000000006"
    }
  }
}
```

--------------------------------

### Run all checks before committing

Source: https://github.com/whitechain-labs/templates/blob/main/whitechain-dapp-nextjs/README.md

Runs lint, typecheck, and unit tests. Also includes e2e tests, which require a one-time install of the e2e test runner.

```bash
pnpm lint && pnpm typecheck && pnpm test
pnpm test:e2e   # run `pnpm test:e2e:install` once first
```

--------------------------------

### Get the template with npx degit

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/README.md

Pulls the Foundry folder alone from the templates repository and changes into the new project directory.

```shell
npx degit whitechain-labs/templates/Foundry whitechain-foundry
cd whitechain-foundry
```

--------------------------------

### Get the Whitechain Hardhat template using degit

Source: https://github.com/whitechain-labs/templates/blob/main/Hardhat/README.md

Pulls the Hardhat folder alone from the templates repository. Requires Node.js 22 or later. Do not reuse mainnet keys; use a throwaway private key funded from the faucet.

```shell
npx degit whitechain-labs/templates/Hardhat whitechain-hardhat
cd whitechain-hardhat
```

--------------------------------

### Log with console2.sol in Forge tests

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/README.md

Use `console2.sol` for logging in Forge tests to get decoded logs in traces. It can be imported indirectly via `Test.sol` or directly. Note that `console2.sol` is recommended over `console.sol` because of a bug that prevents proper decoding of `uint256` and `int256` logs in Forge traces.

```solidity
// import it indirectly via Test.sol
import "forge-std/Test.sol";
// or directly import it
import "forge-std/console2.sol";
...
console2.log(someValue);
```

--------------------------------

### Build and preview the production bundle

Source: https://github.com/whitechain-labs/templates/blob/main/whitechain-dapp-vite/README.md

Builds the static production bundle and previews it locally.

```bash
pnpm build && pnpm preview
```

--------------------------------

### Copy environment file with cp

Source: https://github.com/whitechain-labs/templates/blob/main/Hardhat/README.md

Copies the .env.example file to .env for configuring environment variables.

```shell
cp .env.example .env
```

--------------------------------

### Build and test with forge

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/README.md

Builds the project and runs the test suite. These work before filling in any environment variables, confirming the toolchain is set up.

```shell
forge build
forge test
```

--------------------------------

### Load environment: source .env

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/README.md

Loads the .env file into the shell so $PRIVATE_KEY expands on the command line.

```shell
source .env
```

--------------------------------

### Compile and test the contract

Source: https://github.com/whitechain-labs/templates/blob/main/Hardhat/README.md

Compiles the Solidity contracts and runs the test suite. Expected output shows one Solidity file compiled with solc 0.8.28 and two passing tests.

```shell
npm run compile
npm test
```

```text
Compiled 1 Solidity file with solc 0.8.28 (evm target: cancun)

  Storage
    ✔ starts at zero
    ✔ stores and retrieves a value

2 passing
```

--------------------------------

### Build with multiple Solidity compiler versions for compatibility

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/CONTRIBUTING.md

Run these commands to verify your changes are compatible with all supported Solidity compiler versions (0.6.2, 0.6.12, 0.7.0, 0.7.6, 0.8.0).

```sh
forge build --skip test --use solc:0.6.2
forge build --skip test --use solc:0.6.12
forge build --skip test --use solc:0.7.0
forge build --skip test --use solc:0.7.6
forge build --skip test --use solc:0.8.0
```

--------------------------------

### stdStorage usage: find and checked_write for storage slots

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/README.md

Complete example of using stdStorage to find and write storage slots for public variables, mappings, structs, and assembly-based hidden slots. Requires the Storage contract defined below; note that packed storage variables are not supported by default and require enable_packed_slots().

```solidity
import "forge-std/Test.sol";

contract TestContract is Test {
    using stdStorage for StdStorage;

    Storage test;

    function setUp() public {
        test = new Storage();
    }

    function testFindExists() public {
        // Let's say we want to find the slot for the public
        // variable `exists`. We just pass in the function selector
        // to the `find` command
        uint256 slot = stdstore.target(address(test)).sig("exists()").find();
        assertEq(slot, 0);
    }

    function testWriteExists() public {
        // Let's say we want to write to the slot for the public
        // variable `exists`. We just pass in the function selector
        // to the `checked_write` command
        stdstore.target(address(test)).sig("exists()").checked_write(100);
        assertEq(test.exists(), 100);
    }

    // It supports arbitrary storage layouts, like assembly-based storage locations
    function testFindHidden() public {
        // `hidden` is a random hash of bytes; iterating through slots would
        // not find it. Our mechanism does
        // Also, you can use the selector instead of a string
        uint256 slot = stdstore.target(address(test)).sig(test.hidden.selector).find();
        assertEq(slot, uint256(keccak256("my.random.var")));
    }

    // If targeting a mapping, you have to pass in the keys necessary to perform the find
    // i.e.:
    function testFindMapping() public {
        uint256 slot = stdstore
            .target(address(test))
            .sig(test.map_addr.selector)
            .with_key(address(this))
            .find();
        // in the `Storage` constructor, we wrote that this address' value was 1 in the map
        // so when we load the slot, we expect it to be 1
        assertEq(uint(vm.load(address(test), bytes32(slot))), 1);
    }

    // If the target is a struct, you can specify the field depth:
    function testFindStruct() public {
        // NOTE: see the depth parameter - 0 means 0th field, 1 means 1st field, etc.
        uint256 slot_for_a_field = stdstore
            .target(address(test))
            .sig(test.basicStruct.selector)
            .depth(0)
            .find();

        uint256 slot_for_b_field = stdstore
            .target(address(test))
            .sig(test.basicStruct.selector)
            .depth(1)
            .find();

        assertEq(uint(vm.load(address(test), bytes32(slot_for_a_field))), 1);
        assertEq(uint(vm.load(address(test), bytes32(slot_for_b_field))), 2);
    }
}

// A complex storage contract
contract Storage {
    struct UnpackedStruct {
        uint256 a;
        uint256 b;
    }

    constructor() {
        map_addr[msg.sender] = 1;
    }

    uint256 public exists = 1;
    mapping(address => uint256) public map_addr;
    // mapping(address => Packed) public map_packed;
    mapping(address => UnpackedStruct) public map_struct;
    mapping(address => mapping(address => uint256)) public deep_map;
    mapping(address => mapping(address => UnpackedStruct)) public deep_map_struct;
    UnpackedStruct public basicStruct = UnpackedStruct({
        a: 1,
        b: 2
    });

    function hidden() public view returns (bytes32 t) {
        // an extremely hidden storage slot
        bytes32 slot = keccak256("my.random.var");
        assembly {
            t := sload(slot)
        }
    }
}
```

--------------------------------

### Test contract using stdError.arithmeticError with expectRevert

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/README.md

Example showing how to expect a built-in user-visible revert using the stdError helper. The test contract imports Test.sol, deploys a separate ErrorsTest contract, calls vm.expectRevert with stdError.arithmeticError, then invokes arithmeticError(10) which subtracts 100 and overflows a uint256. The ErrorsTest contract is included.

```solidity

import "forge-std/Test.sol";

contract TestContract is Test {
    ErrorsTest test;

    function setUp() public {
        test = new ErrorsTest();
    }

    function testExpectArithmetic() public {
        vm.expectRevert(stdError.arithmeticError);
        test.arithmeticError(10);
    }
}

contract ErrorsTest {
    function arithmeticError(uint256 a) public {
        a = a - 100;
    }
}
```

--------------------------------

### Deploy to testnet with npm

Source: https://github.com/whitechain-labs/templates/blob/main/Hardhat/README.md

Deploys the contract to Whitechain Sepolia. Expected output includes the deployed address and explorer link.

```shell
npm run deploy:testnet
```

```text
Storage deployed to: 0xYourDeployedAddress
Explorer: https://explorer.testnet.whitechain.io/address/0xYourDeployedAddress
```

--------------------------------

### Log with console.sol for Hardhat compatibility

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/README.md

Use `console.sol` for logging when you need compatibility with Hardhat. It can be imported indirectly via `Test.sol` or directly. Be aware that due to a bug, logs using `uint256` or `int256` types will not be properly decoded in Forge traces.

```solidity
// import it indirectly via Test.sol
import "forge-std/Test.sol";
// or directly import it
import "forge-std/console.sol";
...
console.log(someValue);
```

--------------------------------

### Fetch a template folder with git sparse checkout

Source: https://github.com/whitechain-labs/templates/blob/main/README.md

Use git sparse checkout to fetch only the desired template folder. The first command clones the repository with blob filtering and sparse checkout enabled; the second enters the cloned directory and sets the sparse checkout to the specified folder.

```shell
git clone --filter=blob:none --sparse https://github.com/whitechain-labs/templates
cd templates && git sparse-checkout set <folder>
```

--------------------------------

### Generate cheatcodes from a custom JSON file

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/CONTRIBUTING.md

Run the vm.py script with the --from flag to generate the Vm interface from a custom JSON file instead of the default cheatcodes.json.

```sh
./scripts/vm.py --from path/to/cheatcodes.json
```

--------------------------------

### Run formatting and tests before submitting changes

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/lib/forge-std/CONTRIBUTING.md

Run these commands to ensure your code changes pass formatting and test checks before submitting a pull request.

```sh
forge fmt --check
forge test -vvv
```

--------------------------------

### Repository layout tree

Source: https://github.com/whitechain-labs/templates/blob/main/whitechain-token-lists/README.md

Shows the directory structure of the repository, including data folders for tokens, source, scripts, workflows, and generated output.

```text
.
├── data/
│   ├── WWBT/
│   │   ├── data.json
│   │   └── logo.svg
│   └── USDT.e/
│       ├── data.json
│       └── logo.svg
├── src/                      # chain config, types, build + validation logic
├── scripts/                  # generate + validate CLIs
├── .github/workflows/        # validate on PR; generate + publish on merge to main
├── whitechain.tokenlist.json # generated output – do NOT hand-edit
├── CNAME                      # tokens.whitechain.io (Pages origin)
├── package.json
├── tsconfig.json
└── README.md
```

--------------------------------

### Deploy Storage contract with forge script

Source: https://github.com/whitechain-labs/templates/blob/main/Foundry/README.md

Deploys the Storage contract to Whitechain Sepolia. The --broadcast flag sends the transaction; without it, forge only simulates. The contract address and receipt are written to broadcast/DeployStorage.s.sol/1874/run-latest.json.

```shell
forge script script/DeployStorage.s.sol:DeployStorage \
  --rpc-url whitechain_sepolia \
  --private-key $PRIVATE_KEY \
  --broadcast
```

--------------------------------

### Verify contract with Hardhat

Source: https://github.com/whitechain-labs/templates/blob/main/Hardhat/README.md

Submits the contract to all configured verifiers (Whitechain Blockscout and Sourcify). Append constructor arguments after the address if needed.

```shell
npx hardhat verify --network whitechainSepolia <contract_address>
```

--------------------------------

### Clone the template with degit

Source: https://github.com/whitechain-labs/templates/blob/main/whitechain-dapp-vite/README.md

Use npx degit to pull just the whitechain-dapp-vite folder from the templates repository. Requires Node 20.19+ and pnpm (via Corepack).

```bash
npx degit whitechain-labs/templates/whitechain-dapp-vite whitechain-dapp-vite
cd whitechain-dapp-vite
```
Tokens:
Raw