From 48d5f16f8a4cce5b1b87862369384b99a04dfb96 Mon Sep 17 00:00:00 2001 From: Nero978 Date: Wed, 19 Aug 2026 15:59:23 +0800 Subject: [PATCH 1/4] feat: add VSCode settings for file nesting and formatting --- .vscode/settings.json | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..c149249 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,13 @@ +{ + "explorer.fileNesting.enabled": true, + "explorer.fileNesting.patterns": { + ".gitignore": ".gitattributes, .gitmodules, .gitkeep", + ".env": ".env.*", + "foundry.toml": "foundry.*, remappings.txt", + "Dockerfile": "docker-compose.yml, docker-compose.override.yml, docker-compose.*.yml, .dockerignore" + }, + "editor.codeActionsOnSave": { + "source.fixAll": "explicit" + }, + "editor.formatOnSave": true, +} \ No newline at end of file From 7505c0557eb9e2282f8febf5321c8b6b723b7a58 Mon Sep 17 00:00:00 2001 From: Nero978 Date: Wed, 19 Aug 2026 16:00:24 +0800 Subject: [PATCH 2/4] feat: add Docker configuration and environment setup --- .dockerignore | 12 +++++++++ .env.example | 30 +++++++++++++++++++-- Dockerfile | 12 +++++++++ docker-compose.yml | 66 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 118 insertions(+), 2 deletions(-) create mode 100644 .dockerignore create mode 100644 Dockerfile create mode 100644 docker-compose.yml diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..18709c6 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,12 @@ +.git +.github +.vscode +.idea + +.env +.env.* + +out +cache + +node_modules \ No newline at end of file diff --git a/.env.example b/.env.example index 840673a..421825c 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,28 @@ -PRIVATE_KEY= -RPC_URL=http://127.0.0.1:8545 \ No newline at end of file +# ========================= +# Anvil Configuration +# ========================= + +ANVIL_PORT=8545 +ANVIL_CHAIN_ID=31337 +ANVIL_ACCOUNTS=10 +ANVIL_BALANCE=10000 + +# Development only - DO NOT use in production +ANVIL_MNEMONIC=test test test test test test test test test test test junk + +# ========================= +# NettedX Deployment +# ========================= + +RPC_URL=http://anvil:8545 + +# Private key of Anvil account #0 +# Development only +DEPLOYER_PRIVATE_KEY=0x... + +# ========================= +# Docker +# ========================= + +ANVIL_CONTAINER_NAME=nettedx-anvil +DEPLOYER_CONTAINER_NAME=nettedx-deployer \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..79eee0c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,12 @@ +FROM ghcr.io/foundry-rs/foundry:v1.7.1 + +WORKDIR /app + +COPY . . + +RUN git config --global --add safe.directory /app + +RUN forge build +RUN forge test + +CMD ["forge", "build"] \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..b1160ef --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,66 @@ +services: + anvil: + image: ghcr.io/foundry-rs/foundry:v1.7.1 + container_name: ${ANVIL_CONTAINER_NAME} + + command: + - anvil + - --host + - 0.0.0.0 + - --port + - ${ANVIL_PORT} + - --chain-id + - ${ANVIL_CHAIN_ID} + - --accounts + - ${ANVIL_ACCOUNTS} + - --balance + - ${ANVIL_BALANCE} + - --mnemonic + - ${ANVIL_MNEMONIC} + + ports: + - "${ANVIL_PORT}:${ANVIL_PORT}" + + volumes: + - anvil-data:/anvil-data + + healthcheck: + test: + [ + "CMD", + "cast", + "block-number", + "--rpc-url", + "http://127.0.0.1:${ANVIL_PORT}" + ] + interval: 2s + timeout: 3s + retries: 10 + + deployer: + build: + context: . + dockerfile: Dockerfile + + container_name: ${DEPLOYER_CONTAINER_NAME} + + depends_on: + anvil: + condition: service_healthy + + environment: + RPC_URL: ${RPC_URL} + DEPLOYER_PRIVATE_KEY: ${DEPLOYER_PRIVATE_KEY} + + command: + - forge + - script + - script/Deploy.s.sol + - --rpc-url + - ${RPC_URL} + - --private-key + - ${DEPLOYER_PRIVATE_KEY} + - --broadcast + +volumes: + anvil-data: \ No newline at end of file From 2f8b4ce27488dfe868a75df08dcb4f2e0fb83871 Mon Sep 17 00:00:00 2001 From: Nero978 Date: Wed, 19 Aug 2026 16:08:42 +0800 Subject: [PATCH 3/4] feat: add Docker build workflow for automated image creation and publishing --- .github/workflows/Docker-Build.yml | 55 ++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 .github/workflows/Docker-Build.yml diff --git a/.github/workflows/Docker-Build.yml b/.github/workflows/Docker-Build.yml new file mode 100644 index 0000000..04e002c --- /dev/null +++ b/.github/workflows/Docker-Build.yml @@ -0,0 +1,55 @@ +name: Docker Build + +on: + release: + types: [published] + +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + +jobs: + docker: + name: Build and Push Docker Image + runs-on: ubuntu-latest + + permissions: + contents: read + packages: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Log in to GitHub Container Registry + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract Docker metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=raw,value=latest + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Build and push Docker image + uses: docker/build-push-action@v6 + with: + context: . + file: ./Dockerfile + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max \ No newline at end of file From 012d3f26df3e307c818575ad162526e79f59dcd5 Mon Sep 17 00:00:00 2001 From: Nero978 Date: Wed, 19 Aug 2026 16:21:29 +0800 Subject: [PATCH 4/4] feat: reorganize README structure and enhance Docker deployment section --- README.md | 175 ++++++++++++++++++++++++++---------------------------- 1 file changed, 84 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index cf188c6..ffef359 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,7 @@ 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 pool management, ERC-20 test tokens, and dashboard metrics accessible through Ethereum JSON-RPC. -## Get Started - -### Prerequisites +## Prerequisites Make sure the following tools are installed: @@ -32,6 +30,11 @@ cast --version anvil --version ``` +## Get Started + +> For developers. +> Quickstart for users is available in the [Docker Deployment](#docker-deployment) section. + ### Clone the Repository Clone the repository together with all Git submodules: @@ -74,48 +77,6 @@ To display contract bytecode sizes: forge build --sizes ``` -### Format - -Check whether the contracts follow the project's formatting rules: - -```bash -forge fmt --check -``` - -To automatically format the code: - -```bash -forge fmt -``` - -### Test - -Run the complete test suite: - -```bash -forge test -vvv -``` - -For more detailed execution traces: - -```bash -forge test -vvvv -``` - -You can also run a specific test file: - -```bash -forge test --match-path test/unit/Netting.t.sol -vvv -``` - -The test suite covers the main components of the system, including: - -* Netting -* Settlement -* LiquidityPool -* Mock tokens -* End-to-end settlement flow - ### Local Development Start a local Anvil node: @@ -160,78 +121,80 @@ settlement.setNetting(address(netting)); This allows `Netting` to execute settlement operations through the `Settlement` contract. -### Contract Interaction +## Available Commands -After deployment, contract addresses can be used with `cast` to interact with the blockchain. +### Format -For example, check the available Anvil accounts: +Check whether the contracts follow the project's formatting rules: ```bash -cast rpc eth_accounts --rpc-url http://127.0.0.1:8545 +forge fmt --check ``` -Read the current settlement window: +To automatically format the code: ```bash -cast call \ - $NETTING \ - "currentWindowId()(uint256)" \ - --rpc-url $RPC_URL +forge fmt ``` -The main contracts are: +### Test -```text -Netting -Settlement -LiquidityPool -MockUSDC -MockBond +Run the complete test suite: + +```bash +forge test -vvv ``` -### Dashboard Metrics +For more detailed execution traces: + +```bash +forge test -vvvv +``` -The `Netting` contract provides dashboard metrics through: +You can also run a specific test file: -```solidity -getDashboardMetrics() +```bash +forge test --match-path test/unit/Netting.t.sol -vvv ``` -It returns: +The test suite covers the main components of the system, including: -```text -totalSettlementAmount -netSettlementAmount -liquiditySaved -obligationReduction +* Netting +* Settlement +* LiquidityPool +* Mock tokens +* End-to-end settlement flow + +## Contract Interaction + +After deployment, contract addresses can be used with `cast` to interact with the blockchain. + +For example, check the available Anvil accounts: + +```bash +cast rpc eth_accounts --rpc-url http://127.0.0.1:8545 ``` -The function can be called through JSON-RPC using `cast`: +Read the current settlement window: ```bash cast call \ $NETTING \ - "getDashboardMetrics()(uint256,uint256,uint256,uint256)" \ + "currentWindowId()(uint256)" \ --rpc-url $RPC_URL ``` -These metrics can be queried by the backend through the blockchain's JSON-RPC endpoint. - -The backend needs: - -```text -RPC URL -Netting contract address -Netting ABI -``` - -For local development, the RPC endpoint is: +The main contracts are: ```text -http://127.0.0.1:8545 +Netting +Settlement +LiquidityPool +MockUSDC +MockBond ``` -### ABI +## ABI After running: @@ -255,7 +218,7 @@ 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 +## Environment Variables For local development, you can use a `.env` file: @@ -272,7 +235,37 @@ Make sure `.env` is included in `.gitignore`: .env ``` -### Common Dependency Issues +## 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: + +```bash +cp .env.example .env +``` + +Change the variables in `.env` as needed. + +### Build and Run + +```bash +docker-compose up --build +``` + +## Common Dependency Issues If Foundry reports dependency or submodule errors, first make sure all submodules are initialized and synchronized: @@ -337,7 +330,7 @@ forge build --sizes forge test -vvv ``` -### Project Structure +## Project Structure The main project structure is: @@ -363,7 +356,7 @@ NettedX-Blockchain/ └── README.md ``` -### Development Workflow +## Development Workflow The recommended local development workflow is: @@ -387,7 +380,7 @@ Interact Using cast Connect Backend / Frontend ``` -### Repository +## Repository GitHub: