Create test framework to ensure SDK non-regression

[mod]

Objectives

Ensure any changes don't break the SDK, if build is successful on main branch, we should publish a new patchset.

Typescript and go code, should deploy the nitrolite artifacts in a simulated backend
and run unit tests.

For typescript I believe @ethereumjs/evm should be a good fit.
For golang simply using what's available in go-ethereum

[akushniruk]

#180

[akushniruk]

• What We Have in Place (Summary - SDK <> Custody Contract):

  • Test Runner & Environment:
    • Jest is used as the test runner (jest.integration.config.js).
    • A comprehensive setup (test/integration/setup.ts and potentially orchestrated by scripts/test-setup.sh if still used for CI) handles:
      • Local Anvil instance management (snapshotting and resetting).
      • Deployment of Custody, DummyAdjudicator (or a similar test adjudicator), and TestERC20 contracts. CREATE2 is likely used via Deploy.s.sol for deterministic addresses when scripts/test-setup.sh is involved, or direct deployment via deployContract helper for local test runs.
      • Funding of test accounts (Alice, Bob) with both ETH and TestERC20 tokens.
  • NitroliteClient Initialization & Configuration:
    • Successful client instantiation with necessary public/wallet clients and contract addresses.
    • Verification of connected account and configured addresses.
  • Account & Token Management (via NitroliteClient):
    • Fetching on-chain account balances (ETH and ERC20).
    • Fetching ERC20 token balances and allowances.
    • Approving ERC20 tokens for the Custody contract (client.approveTokens).
  • Asset Deposits (via NitroliteClient):
    • Successful deposit of ERC20 tokens into the Custody contract.
    • Successful deposit of ETH into the Custody contract.
  • Basic Channel Operations (via NitroliteClient):
    • Creating a new state channel (client.createChannel) with initial allocations.
    • Depositing funds and creating a channel in a single operation (client.depositAndCreateChannel).
    • Fetching a list of open channels (client.getOpenChannels).
  • Underlying NitroliteService Interactions: The client methods above implicitly test the corresponding prepare* and direct execution methods in NitroliteService for these happy path scenarios.

• What's Missing / Next Steps to Finalize & Enhance Integration Tests:

  1. True End-to-End Testing with Clearnode Integration:
     • Current Scope Limitation: Our existing integration tests primarily validate the SDK's direct on-chain interactions with the Custody contract.
     • Missing Piece: A crucial next step for comprehensive end-to-end testing is to integrate Clearnode. This involves:
       • Setting up a Clearnode instance as part of the test environment.
       • Modifying tests (or creating new ones) where SDK actions trigger off-chain message passing through Clearnode between participants (e.g., proposing states, exchanging signatures).
       • Validating that Clearnode correctly relays messages and that participants can react to these messages to progress the channel state or resolve disputes.
       • This will test the full off-chain communication loop that complements the on-chain contract logic.
  2. Complete Channel Lifecycle Scenarios (On-Chain Aspects):
     • Joining a Channel: Implement tests for a second participant (Bob) calling client.joinChannel(channelId, participantIndex, signature). This requires generating the necessary off-chain signature for the initial state.
     • Off-Chain State Updates & Checkpointing (On-Chain Submission):
       • Simulate off-chain state progression (e.g., Alice and Bob sign new states, potentially facilitated via mock Clearnode messages initially, then real ones).
       • Test client.checkpoint(channelId, candidateState, proofs) with these new states being submitted to the contract.
     • Cooperative Close: Test client.closeChannel(channelId, finalState, proofs) where finalState is agreed upon and signed by all participants.
     • Dispute Resolution (Challenge Lifecycle On-Chain):
       • Initiate client.challenge(channelId, candidateState, proofs, challengerSignature).
       • Test responding to a challenge with a more recent, valid state (another challenge call or a specific respondToChallenge method if available).
       • Test client.closeChannel(...) after a challenge period has successfully expired without a valid response.
     • Channel Resizing: Implement tests for client.resizeChannel(channelId, candidateState, proofs).
  3. Withdrawal Operations:
     • Thorough testing of client.withdraw(assetAddress, amount) for both ETH and ERC20 tokens from the Custody contract. Include scenarios for sufficient and insufficient available balances.
  4. Advanced State Management & Signatures (Off-Chain Focus):
     • Focus on the stateWalletClient implementation and ensure correct off-chain state signing and verification logic is implicitly tested through channel operations that require signed states (checkpoint, challenge, close). This becomes even more critical when Clearnode is involved for message exchange.
     • Test scenarios involving multiple sequential state updates and their impact on checkpointing/challenges.
  5. Robust Error Handling & Edge Case Testing (On-Chain):
     • Submitting transactions with invalid signatures (e.g., for joining, checkpointing, challenging, closing).
     • Attempting operations with incorrect state versions, nonces, or inconsistent data.
     • Testing adjudicator-specific logic in more detail (e.g., how the DummyAdjudicator handles different states during challenges or closes).
     • Operations on non-existent, already closed, or actively challenged channels.
     • Replay attacks or out-of-order on-chain operations.
     • Insufficient funds for gas or for the operation itself.
  6. SDK Method Coverage (Targeted): Systematically review NitroliteClient and NitroliteService to ensure all public methods that result in on-chain interactions have corresponding integration tests.
  7. Improve test-setup.sh Reliability (If used for CI/automated full runs):
     • Critical (if scripts/test-setup.sh is the primary entry point for full test runs): Ensure it parses deployed contract addresses from the JSON artifact files generated by forge script (in the broadcast/ directory) instead of relying on stdout parsing.

#180 - merged