test: add E2E lifecycle tests and Robinhood fork tests

.github/workflows/ci.yml

@@ -33,6 +33,33 @@ jobs:
           FOUNDRY_PROFILE: ci
         run: forge test -vvv
 
+  contracts-fork:
+    name: Fork Tests (Robinhood testnet)
+    runs-on: ubuntu-latest
+    # Always runs but skips the fork test step when secret is unavailable
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Fetch Solidity dependencies
+        run: |
+          git clone --depth 1 --branch v5.6.1 https://github.com/OpenZeppelin/openzeppelin-contracts.git lib/openzeppelin-contracts
+          git clone --depth 1 --branch v5.6.1 https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable.git lib/openzeppelin-contracts-upgradeable
+          git clone --depth 1 https://github.com/foundry-rs/forge-std.git lib/forge-std
+
+      - name: Run Fork Tests
+        env:
+          FOUNDRY_FORK: "1"
+          ROBINHOOD_RPC_URL: ${{ secrets.ROBINHOOD_RPC_URL }}
+        run: |
+          if [ -z "$ROBINHOOD_RPC_URL" ]; then
+            echo "::notice::Skipping fork tests — ROBINHOOD_RPC_URL secret not configured"
+            exit 0
+          fi
+          forge test --match-contract ForkTest --fork-url "$ROBINHOOD_RPC_URL" -vvv
+
   sdk:
     name: SDK (vitest)
     runs-on: ubuntu-latest

README.md

@@ -383,6 +383,57 @@ Running the fuzz suite at higher intensity:
 FOUNDRY_PROFILE=ci forge test
 ```
 
+## Testing
+
+The test suite is organized into three tiers:
+
+### Unit Tests (default)
+
+Test individual contract functions in isolation. These run on Foundry's in-memory EVM and require no external network.
+
+```bash
+forge test                        # all unit tests
+FOUNDRY_PROFILE=ci forge test     # denser fuzz runs (5000 iterations)
+```
+
+### E2E Integration Tests
+
+Cover the full agent lifecycle: `register → stake → propose/finalize reputation → slash → zero-reputation`. These run in-memory with deployed fixture contracts.
+
+```bash
+forge test --match-contract E2EIntegrationTest -vvv
+```
+
+Key scenarios tested:
+- Full lifecycle from registration to slash
+- Slash dispute and agent reinstatement
+- Reputation challenge (committee rejects bad score)
+- Unbonding period enforcement
+- Slash sweeping unbonding queue (dodge prevention)
+- Multiple epochs of score evolution
+- Multiple independent agents
+
+### Fork Tests (Robinhood testnet)
+
+Validate deployed contracts on chain `46630` match expected interfaces and state. These require RPC access to Robinhood testnet and are skipped automatically when the RPC is unavailable.
+
+```bash
+# Using foundry.toml alias (public RPC, rate-limited)
+FOUNDRY_FORK=1 forge test --match-contract ForkTest --fork-url robinhood_testnet -vvv
+
+# Using custom RPC URL (Alchemy, higher rate limits)
+FOUNDRY_FORK=1 forge test --match-contract ForkTest --fork-url https://robinhood-testnet.g.alchemy.com/v2/YOUR_KEY -vvv
+```
+
+Fork tests validate:
+- Deployed bytecode exists at expected addresses
+- ERC20/Identity/Reputation/Staking interfaces match
+- Cross-contract role linkages are correct
+- Read paths work against live state
+- Simulated write paths (via `vm.prank`) execute correctly
+
+**CI note:** Fork tests run in a separate CI job that requires the `ROBINHOOD_RPC_URL` secret. External contributors' PRs will skip this job (the main test suite still runs). Maintainers can add the secret to enable fork validation.
+
 ---
 
 ## Access Control Summary