Feature: Coordinator

.github/workflows/coverage-report.yml

@@ -34,13 +34,16 @@ jobs:
             'src/proto/**' \
             'src/core/PacketHandler.sol' \
             'src/core/ContractRegistry.sol' \
+            'src/core/TxAuthManagerBase.sol' \
+            'src/core/TxManagerBase.sol' \
+            'src/core/TxRunnerBase.sol' \
             -o lcov.filtered.info
 
       - name: Report code coverage
         uses: zgosalvez/github-actions-report-lcov@v5
         with:
           coverage-files: lcov.filtered.info
-          minimum-coverage: 100
+          minimum-coverage: 96
           artifact-name: code-coverage-report
           github-token: ${{ secrets.GITHUB_TOKEN }}
           update-comment: true

.github/workflows/gas-snapshot-diff.yml

@@ -0,0 +1,109 @@
+name: Gas Snapshot Diff Report
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'test/**'
+      - 'foundry.toml'
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  gas-diff:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '25'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Fetch .gas-snapshot from Base Branch
+        run: |
+          BASE_BRANCH="origin/${{ github.base_ref }}"
+          echo "Fetching snapshot from $BASE_BRANCH..."
+
+          if git show "$BASE_BRANCH:.gas-snapshot" > .gas-snapshot 2>/dev/null; then
+            echo "Successfully fetched .gas-snapshot from base branch."
+          else
+            echo "⚠️ .gas-snapshot not found in base branch."
+            exit 0
+          fi
+
+      - name: Run Snapshot Diff
+        id: run_diff
+        shell: bash
+        run: |
+          npm run snapshot:diff | \
+          sed 's/\x1b\[[0-9;]*m//g' | \
+          grep -v "^>" | \
+          grep -vE "^\[PASS\]|^Ran |^Suite result" | \
+          grep -v "gas: 0 (0.000%)" | \
+          grep -v "compilation skipped" | \
+          sed '/^$/d' | \
+          sed -E 's/\(gas: ([0-9])/(gas: +\1/g' > gas_diff.txt
+
+          cat gas_diff.txt
+
+      - name: Comment Gas Diff on PR
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require('fs');
+            const diffOutput = fs.readFileSync('gas_diff.txt', 'utf8');
+
+            if (diffOutput.trim() === '') {
+              console.log("No gas changes detected.");
+              return;
+            }
+
+            const body = `### ⛽ Gas Usage Changes
+
+            Comparison against \`${{ github.base_ref }}\` branch:
+
+            <details>
+            <summary>Click to view gas diff</summary>
+
+            \`\`\`diff
+            ${diffOutput}
+            \`\`\`
+
+            </details>
+
+            *Calculated by Foundry Gas Snapshot Action*`;
+
+            const { owner, repo, number } = context.issue;
+            const comments = await github.rest.issues.listComments({
+              owner,
+              repo,
+              issue_number: number,
+            });
+
+            const botComment = comments.data.find(c => c.body.includes('### ⛽ Gas Usage Changes'));
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: botComment.id,
+                body: body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: number,
+                body: body
+              });
+            }

.github/workflows/gas-snapshot-update.yml

@@ -0,0 +1,40 @@
+name: Update Gas Snapshot on Merge
+
+on:
+  push:
+    branches:
+      - develop # ToDo: change develop to main when main branch is ready
+    paths:
+      - 'src/**'
+      - 'test/**'
+      - 'foundry.toml'
+
+permissions:
+  contents: write
+
+jobs:
+  update-snapshot:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '25'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate Snapshot
+        run: npm run snapshot
+
+      - name: Commit and Push changes
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "chore(gas): update .gas-snapshot [skip ci]"
+          file_pattern: .gas-snapshot
+          branch: ${{ github.ref }}

.github/workflows/test.yml

@@ -8,7 +8,7 @@ jobs:
     steps:
 
     - name: Set up Go 1.24
-      uses: actions/setup-go@v1
+      uses: actions/setup-go@v6
       with:
         go-version: 1.24
       id: go
@@ -22,7 +22,7 @@ jobs:
     - name: Resolve dependencies
       run: npm install
 
-    - name: Setup ganache-cli
+    - name: Setup chain & Deploy contracts
       run: NO_GEN_CODE=1 ./script/setup.sh development
 
     - name: Test

.husky/pre-commit

@@ -3,6 +3,4 @@
 
 set -e
 
-npm run fmt:sol
-
-git add -A
+npx lint-staged

.lintstagedrc.json

@@ -0,0 +1,3 @@
+{
+  "*.sol": ["npm run fmt:sol"]
+}

README.md

@@ -7,28 +7,47 @@ This is a solidity implementation of [Cross Framework](https://github.com/datach
 
 Currently, it provides the following features:
 - the registry feature that allows developers to register their contracts
-- the participant feature of the simple commit protocol
+- the coordinator feature of the simple commit protocol
+- the participant features for the simple-commit and two-phase commit protocols
 - it's implemented on top of [yui-ibc-solidity](https://github.com/hyperledger-labs/yui-ibc-solidity)
 
-A coordinator feature of the simple commit and two-phase commit will be provided in the future.
+The coordinator feature of the two-phase commit will be provided in the future.
 
-## Contract module development
+## Demo
 
-A developer who develops contract using Cross Framework need to implement IContractModule, which is defined in [IContractModule.sol](./src/core/IContractModule.sol).
+For an ERC20 atomic swap demo, please refer to [ethereum-cross-demo](https://github.com/datachainlab/ethereum-cross-demo)
+
+## Contract module development
 
-```
 // IContractModule defines the expected interface of a contract module on Cross Framework
+```solidity
 interface IContractModule {
-    // onContractCall is a callback function that is called at the commit(simple-commit) phase
-    function onContractCall(CrossContext calldata context, bytes calldata callInfo) external returns (bytes memory);
+    // onContractCommitImmediately is a callback function that is called on the participant chain to execute the transaction logic immediately
+    // This function is intended to be used only in the simple-commit protocol
+    function onContractCommitImmediately(CrossContext calldata context, bytes calldata callInfo)
+        external
+        returns (bytes memory);
+
+    // onContractPrepare is a callback function that is called at the prepare(2pc) phase
+    function onContractPrepare(CrossContext calldata context, bytes calldata callInfo) external returns (bytes memory);
+
+    // onCommit is a callback function that is called at the commit(2pc) phase
+    // It is expected that it commits the changes in the contract module
+    // IMPORTANT: This function MUST NOT revert.
+    function onCommit(CrossContext calldata context) external;
+
+    // onAbort is a callback function that is called at the commit(2pc) phase
+    // It is expected that it aborts the changes in the contract module
+    // IMPORTANT: This function MUST NOT revert.
+    function onAbort(CrossContext calldata context) external;
 }
 ```
 
-- Currently, only one function `onContractCall` is defined, which implements the process of a transaction called via the cross-chain transaction.
+- For the current simple-commit coordinator flow, the coordinator-side participant uses `onContractPrepare` to execute and lock state changes, and later finalizes them with `onCommit` or `onAbort` based on the acknowledgement from the counterparty.
 
-- The return value of `onContractCall` is emitted as an Event `OnContractCall` with the transaction info.
+- The counterparty participant executes the incoming call and finalizes immediately via `onContractCommitImmediately`.
 
-- If it gets an unexpected call, the developer need to perform `revert` in the contract. This will request the coordinator to abort the transaction.
+- IMPORTANT: `onCommit` and `onAbort` MUST NOT revert.
 
 ## How to deploy a contract module
 

chains/docker-compose.yml

@@ -20,8 +20,3 @@ services:
       interval: 2s
       timeout: 1s
       retries: 30
-  geth:
-    build: ./geth
-    ports:
-      - 8545:8545
-      - 8546:8546