Marketplace EVM Stack

Standalone Docker stack for testing marketplace EVM drivers against the same Boltz + EVM environment.

The stack is intentionally Nostr-agnostic and app-agnostic. It provides:

• Boltz regtest services
• Rootstock-style Anvil chain 33
• Arbitrum-style Anvil chain 412346
• Boltz EVM swap contracts
• mock tBTC and USDT
• Uniswap V3 routing contracts for Boltz rates
• MultiEscrow deployed from @sudonym-btc/marketplace-evm-contracts for escrow and auction bid locks
• local ERC-4337 account-abstraction services: Alto bundler and mock paymaster
• a standalone Boltz regtest Bitcoin node when run directly
• a generated JSON config consumed by TypeScript and Dart tests

Usage

git submodule update --init --recursive
# Standalone checkout: point to the canonical built contract package.
export MARKETPLACE_EVM_CONTRACTS_DIR=/path/to/nmdk/dependencies/marketplace-evm-contracts
./scripts/up.sh
./scripts/wait.sh

The NMDK aggregate scripts discover that same canonical package automatically. No contract artifact snapshots are maintained in this stack.

The development stack supports only the current canonical escrow (v7). Its initializer rejects an existing contract with a different EIP-712 domain before writing driver trust configuration. Contract bytecode is immutable: an old v6 contract is replaced by a fresh deployment, never upgraded in place. This is unreleased software, so disposable development chains, seeded events and operation journals may be reset instead of migrated. For the standalone stack:

./scripts/reset.sh
./scripts/up.sh

reset.sh removes this stack's development data. Consumers should clear their old local operation journals and reseed against the generated address config. No compatibility implementation or v6 signing path is retained.

The scripts run the standalone test instance with Compose project marketplace-evm-stack, high host ports, and ./data as the data directory. They are convenience wrappers around the Compose file; the real lifecycle work is done by Compose services and one-shot init containers.

The generated test config is written to:

data/config/marketplace-evm-stack.json

For each swap-enabled chain, the config includes boltzTrust: the authoritative ERC20Swap address plus the permitted token, Permit2, and Universal Router call targets, their exact selectors and semantic decoder IDs, and SHA-256 hashes calculated from eth_getCode after deployment. Token rules permit only exact approve/transfer funding calls, which are then bound to the decoded swap amount and router. Consumers MUST use these local deployment roots before accepting provider-generated calls; values returned by the Boltz API are not trust roots.

The standalone stack uses fixed localhost ports by default:

• Arbitrum RPC: http://127.0.0.1:18546
• Arbitrum explorer: http://127.0.0.1:15100
• Rootstock RPC: http://127.0.0.1:18545
• Boltz API: http://127.0.0.1:19001/v2
• Bundler: http://127.0.0.1:4337
• Paymaster: http://127.0.0.1:3010

Consumer packages should point their integration tests at that file:

MARKETPLACE_EVM_STACK_CONFIG=/path/to/marketplace-evm-stack/data/config/marketplace-evm-stack.json

For the default standalone stack, consumers can also infer the config from the default host ports and deterministic contract addresses.

Running Two Stacks

Running a standalone test stack and a parent-project-included stack at the same time is supported. The Compose file deliberately avoids a top-level project name, fixed container names, and fixed global volume names.

The remaining shared host resources are published ports and the data directory. Give each standalone stack its own project name, ports, and data directory:

MARKETPLACE_EVM_STACK_PROJECT=marketplace-evm-test \
MARKETPLACE_EVM_STACK_DATA_DIR=./data-test \
MARKETPLACE_EVM_ARBITRUM_RPC_PORT=28546 \
MARKETPLACE_EVM_ROOTSTOCK_RPC_PORT=28545 \
MARKETPLACE_EVM_BOLTZ_API_PORT=29001 \
./scripts/up.sh

When this Compose file is included by another project, the parent Compose project namespaces containers, networks, and volumes. The parent project only needs to choose non-conflicting host ports if it publishes the same services as a running standalone test stack.

To stop the stack:

./scripts/down.sh

To remove generated chain data:

./scripts/reset.sh