Exploring Cross-Chain Testing Options: Multi-Chain vs. Pure JS

[amessbee]

Agoric provides a unique environment for building and deploying smart contracts in JavaScript, with a focus on secure interoperability and cross-chain solutions. For developers writing orchestration logic—that is, contracts designed to facilitate actions across multiple blockchains—there are two primary ways to test such code:

1. The Multi-Chain Local Testing Environment
2. A Pure JavaScript (JS) Approach

Below is a formal overview of both methods, why you might choose one over the other, and a practical example of how to implement the Pure JS approach using the Agoric SDK repository.

---

1. The Multi-Chain Local Testing Environment

1.1 What It Is

The multi-chain testing setup launches multiple Cosmos-based local chains (typically three), complete with IBC connections and a relayer between every pair of chains. This environment replicates a realistic multi-chain scenario where assets and messages can flow across chains via the Inter-Blockchain Communication (IBC) protocol.

1.2 Advantages

• Realistic Cross-Chain Integration: You can observe actual on-chain behavior and interactions, mimicking production scenarios more closely.
• End-to-End Testing: All components—chains, relayers, and contracts—run together, giving a high-fidelity test of deployment, transaction handling, timeouts, acknowledgments, etc.

1.3 Disadvantages

• Complex Setup: Currently it takes around ten minutes to just load multichain-testing environment and doing it first time a bit daunting for the uninitiated.
• Slower Feedback: Iterating over updating contract/tests and waiting for chain confirmations can slow down the development cycle.

1.4 Best Use Cases

• Final Integration Testing: Before you go live on testnets or mainnets, you’ll want to verify that your orchestration logic holds up under real IBC dynamics.

---

2. The Pure JS Approach

2.1 What It Is

The Pure JS approach allows you to run your Agoric contracts locally in a single process without starting multiple Cosmos-based chains. Rather than using IBC for cross-chain communication, you mock or emulate those interactions in JavaScript (and guess what? Folks at Agoric have already wired up many of these mocks!). This yields rapid test results and simplifies your development workflow.

2.2 Advantages

• Instant Feedback: No chain or relayer overhead means quicker iterations and faster debug cycles.
• Lightweight Setup: You only need the Agoric SDK codebase and a JavaScript test runner (i.e., AVA).

2.3 Disadvantages

• Not a True Multi-Chain Test: Since IBC is mocked, issues related to chain timeouts, channel handshakes, or multi-chain synchronization aren’t fully tested.
• Less Realistic Environment: Any chain-specific constraints (block times, gas limits, etc.) aren’t exercised in this approach.

2.4 Best Use Cases

• Unit-Level Testing: Quickly validate your contract’s logic and flows.
• Early Development: When you’re focused on correctness of orchestration steps and want rapid iteration before tackling the complexities of multi-chain deployment.

---

3. Implementing the Pure JS Approach in the Agoric SDK

To illustrate the Pure JS approach, we’ll focus on the organizational pattern used within the agoric-sdk repository’s Orchestration package:

1. Clone the Agoric SDK

   git clone https://github.com/Agoric/agoric-sdk.git
   cd agoric-sdk

2. Write Your Contract Logic

   • Within packages/orchestration/src/examples/, create two files:
     1. A contract file (e.g., myCrossChainContract.js).
     2. A flows file (e.g., myCrossChainFlows.js) that defines or orchestrates how messages and asset transfers occur durably.

   This directory already contains several examples—like the send-anywhere contract—that illustrate cross-chain transfers. You can reference those to structure your own.

3. Create Corresponding Tests

   • Place your test scripts in packages/orchestration/test/.
   • For instance, test-myCrossChainContract.js might import your contract and flows, spin up mock IBC calls (e.g., send/receive/ack), and verify expected behavior.

The “Send Anywhere” contract is a reference implementation that demonstrates how to facilitate the transfer of assets from one chain to another. You can find it at:

• Contract Files: packages/orchestration/src/examples/send-anywhere.contract.js and packages/orchestration/src/examples/send-anywhere.flows.js
• Test File: packages/orchestration/test/examples/send-anywhere.test.ts

By reviewing these files, you can see how Agoric contracts handle cross-chain flows in a purely JS environment. The relevant documentation is provided here:
Send Anywhere Contract Walkthrough

In these examples, mock or simplified IBC-like calls show how your contract might behave when it “receives” or “sends” tokens to another chain. You run the tests using standard yarn test commands, relying solely on JavaScript to validate logic without launching multiple chains.

---

4. Recommended Development Flow

1. Start with the Pure JS Approach

   • Write your contract logic in src/examples/.
   • Quickly test with mock cross-chain messages in the single-process environment.
   • Fix any logical or flow-related bugs.

2. Move to the Multi-Chain Environment

   • Deploy your contract to the local multi-chain setup.
   • Test actual IBC packet transmission, timeouts, and chain confirmations.
   • Inspect logs and relayer outputs to ensure correct channel handshakes and packet acknowledgments.

3. Deploy to a Real Testnet

   • Once confident in local tests, proceed to an official Agoric testnet.
   • Validate your orchestration in a distributed environment with real block times and potential network delays.

4. Finalize on Mainnet

   • After passing testnet validation, consider a mainnet deployment with the confidence your logic has been tested at all levels.

---

5. Conclusion

Agoric’s orchestration paradigm unlocks powerful cross-chain capabilities, but it also introduces additional complexity around IBC, multi-chain state management, and asynchronous message handling. The Pure JS Approach offers a rapid, low-overhead testing solution for early development and unit-level validations, while the Multi-Chain Local Testing Environment provides end-to-end fidelity needed before real-world deployments.

For maximum productivity and reliability:

1. Iterate rapidly with the pure JS approach.
2. Integrate comprehensively with the multi-chain setup.
3. Validate and finalize on a public testnet.

Agoric’s open-source SDK (with its orchestration package) offers a well-structured example of this best-practice approach, making cross-chain development simpler, more approachable, and (ultimately) more robust.

---

Resources & Further Reading

• Agoric Documentation
• Send Anywhere Contract Walkthrough
• Agoric SDK GitHub