NettedX Blockchain

NettedX Blockchain is the smart contract layer of the NettedX settlement system.

The project implements blockchain-based trade netting and settlement using Solidity and Foundry. It includes settlement management, netting, liquidity buffer management, ERC-20 test tokens, and other functionalities.

Prerequisites

Make sure the following tools are installed:

• Foundry
• Git

Tips: On macOS, Foundry can be installed with Homebrew.

Verify the installation:

forge --version

Get Started

For developers. Quickstart for users is available in the Docker Deployment section.

Clone the Repository

Clone the repository together with all Git submodules:

git clone --recurse-submodules https://github.com/NettedX/NettedX-Blockchain.git
cd NettedX-Blockchain

If you have already cloned the repository without submodules, initialize them with:

git submodule update --init --recursive

Verify the dependencies:

git submodule status

You should see the required dependencies under:

lib/forge-std
lib/openzeppelin-contracts

Build

Compile all Solidity contracts:

forge build

Local Development

Start a local Anvil node:

anvil

The default RPC endpoint is: http://127.0.0.1:8545

Then deploy contracts using Foundry's forge command.

forge script script/Deploy.s.sol --rpc-url http://127.0.0.1:8545 --broadcast

From now on, all contracts have been deployed to the local Anvil blockchain, and you can start the Backend to interact with the smart contracts via RPC .

Docker Deployment

For production or users.

The project provides a Dockerized development environment containing an Anvil private blockchain and the NettedX smart contracts.

Prerequisites

• Docker
• Docker Compose
• Cloned repository with submodules initialized

No local Foundry installation is required.

Configuration

Copy the example environment file:

cp .env.example .env

Change the variables in .env as needed.

MOCK_USDC_ADDRESS and MOCK_BOND_ADDRESS control whether deployment creates new mock tokens or reuses existing ones:

• Leave both values empty for the first deployment on a new chain.
• Set them to deployed contract addresses to preserve token balances and total supply.
• If a configured address has no contract code, deployment fails instead of silently replacing the token.

Production releases automatically load both addresses from address-data/addresses.json, snapshot all managed account balances and token supplies, and verify that the complete mock-token state is unchanged after deployment. Only an intentional chain reset should remove the address file and deploy new mock tokens.

Build and Run

docker-compose up --build

This also starts the automatic window keeper. Anvil mines at the configured ANVIL_BLOCK_TIME interval, and the keeper calls freezeWindow() and executeWindow() as each settlement window becomes ready. The keeper uses the cast binary already included in the blockchain image; no separate language runtime is required. See keeper/README.md for operation and configuration details.

Available Commands

Format

To automatically format the code:

forge fmt

Test

Run the complete test suite:

forge test -vvv

Contract Interaction

After deployment, contract addresses can be used with cast to interact with the blockchain.

For example, check the available Anvil accounts:

cast rpc eth_accounts --rpc-url http://127.0.0.1:8545

Read the current settlement window:

cast call \
  $NETTING \
  "currentWindowId()(uint256)" \
  --rpc-url $RPC_URL

The main contracts are:

Netting
Settlement
LiquidityBuffer
MockUSDC
MockBond

ABI

After running:

forge build

Foundry generates contract artifacts under:

out/

For example:

out/Netting.sol/Netting.json

The generated artifact contains the contract ABI and bytecode.

The ABI can be used by the backend or frontend to interact with the deployed smart contract.

Environment Variables

You can use a .env file to config the project, please refer to .env.example for the required variables.

Common Dependency Issues

If Foundry reports dependency or submodule errors, first make sure all submodules are initialized and synchronized:

git submodule update --init --recursive

Check the current submodule revisions:

git submodule status

If a dependency is marked as dirty, for example:

cab19933...-dirty

the dependency contains local uncommitted changes. Inspect them before continuing:

cd lib/openzeppelin-contracts
git status
git diff

If the changes are unintended, restore the dependency:

git reset --hard
git clean -fd

Then return to the project root:

cd ../..

Finally, verify that the working tree is clean:

git status

CI

Every push and pull request runs the Foundry CI pipeline, which checks:

1. Foundry installation
2. Solidity formatting
3. Contract compilation
4. Contract bytecode sizes
5. Complete test suite

You can run the same checks locally before pushing:

forge fmt --check
forge build --sizes
forge test -vvv

Project Structure

The main project structure is:

NettedX-Blockchain/
├── src/
│   ├── core/
│   │   ├── Netting.sol
│   │   ├── Settlement.sol
│   │   └── LiquidityBuffer.sol
│   ├── interfaces/
│   └── libraries/
├── test/
│   ├── unit/
│   └── integration/
├── script/
│   ├── Deploy.s.sol
│   └── token_state_check.py
├── lib/
│   ├── forge-std/
│   └── openzeppelin-contracts/
├── foundry.toml
├── .gitmodules
└── README.md

Development Workflow

The recommended local development workflow is:

Clone Repository
      ↓
Initialize Submodules
      ↓
Build Contracts
      ↓
Run Tests
      ↓
Start Anvil
      ↓
Deploy Contracts
      ↓
Get Contract Addresses
      ↓
Interact Using cast
      ↓
Connect Backend / Frontend

Repository

GitHub: NettedX-Blockchain