skunk-net-e2e/LOCAL-E2E.md

# Local Docker-First Stack

This workspace can be run locally on Arch without shell-profile exports.

For the current live checkpoint, known blocker, and exact repo matrix, see
`CHECKPOINT-2026-04-03.md` and `WORKSPACE-MANIFEST.md`.

The setup below uses top-level dependency checkouts:

- `wire-sysio` in Docker, using the maintained Dockerfile under `wire-sysio/etc/docker/Dockerfile`
- `wire-ethereum` in a Node 20 container on a local Hardhat network
- `capital-staking` in a custom Anchor/Solana toolchain container against the local `solana-docker-setup` genesis validator

## What I Could Confirm

- The remote setup document at `swarm.gitgo.app/.../TESTNET-SETUP-README.md` returned `Not found` on April 2, 2026, so this runbook is based on the local repos and `OPP.pdf`.
- `OPP.pdf` is still useful for the protocol shape, but message encoding details are stale because the live code is moving to protobuf-backed payloads.
- `wire-ethereum` still models OPP delivery around sequential epoch envelopes.
- `capital-staking` is the Solana-side outpost/wire harness in this workspace.
- `solana-docker-setup` is now the intended local validator path so epoch timing is configurable through `SOLANA_SLOTS_PER_EPOCH`.
- `wire-sysio` contains the local node/bootstrap path plus the batch-operator relay implementation we are exercising in this workspace.
- The current Solana withdraw flow still has a placeholder instead of real OPP emission:
  `capital-staking/programs/liqsol-core/src/instructions/wire_syndication/desyndicate_liqsol.rs`

## One-Time Setup

```bash
cd /home/dtaghavi/Documents/Projects/skunk-net
cp .env.local.example .env.local
```

Then use the checked-in wrapper:

```bash
./local-compose.sh ps
```

Nothing in this flow depends on `~/.bashrc`, and the wrapper injects your live uid/gid at runtime so container-generated files stay owned by your Arch user. Adjust `.env.local` if you want different ports, wallet path, or ledger location.

Important Solana knobs:

- `SOLANA_SLOTS_PER_EPOCH=64` keeps local epoch turnover fast for tests.
- `SOLANA_RUN_SH_VALIDATOR_ARGS` lets you append raw `agave-validator` flags from `.env.local`.

## Build The Containers

```bash
./local-compose.sh build capital-staking-dev wire-sysio-dev
```

If you also need to rebuild the Solana validator image explicitly:

```bash
./local-compose.sh build solana-validator
```

`wire-sysio-dev` is the expensive image because it builds the Wire toolchain and Clang 18 layer. The upstream Wire docs call out a 32 GiB RAM expectation for this build path.

## Solana / Capital Staking

Start the local validator:

```bash
./local-compose.sh up -d solana-validator
```

Check the local epoch cadence:

```bash
./local-compose.sh run --rm --no-deps capital-staking-dev bash -lc '
  solana -u "$ANCHOR_PROVIDER_URL" epoch-info
'
```

Reset the local Solana ledger when you want a fresh cluster:

```bash
./local-compose.sh down -v
./local-compose.sh up -d solana-validator
```

Prepare program IDs, build, deploy, and initialize the local cluster:

```bash
./local-compose.sh run --rm capital-staking-dev bash -lc '
  solana config set --url "$ANCHOR_PROVIDER_URL" --keypair "$ANCHOR_WALLET" &&
  ./bash-scripts/prep-anchor-toml.sh &&
  npm ci &&
  ./bash-scripts/reset-local-cluster.sh --wait-for-cluster
'
```

Run the Wire-related Solana suites:

```bash
./local-compose.sh run --rm capital-staking-dev bash -lc '
  solana config set --url "$ANCHOR_PROVIDER_URL" --keypair "$ANCHOR_WALLET" &&
  npm ci &&
  npm run test:wire-syndication &&
  npm run test:wire-pretokens &&
  npm run test:bar
'
```

Those are the closest existing local tests to the instant-swap / outpost lifecycle in this checkout.

## Ethereum / OPP

For contract-level OPP validation you can either run one-shot tests or keep a local Hardhat node up.

One-shot OPP tests:

```bash
./local-compose.sh run --rm wire-ethereum-dev bash -lc '
  cd /workspace/wire-ethereum &&
  npm ci &&
  npx hardhat test src/test/outpost/OPPSend.ts src/test/outpost/OPPRecv.ts
'
```

Long-lived local JSON-RPC:

```bash
./local-compose.sh up -d hardhat
```

Then run additional tests or scripts from a disposable shell:

```bash
./local-compose.sh run --rm wire-ethereum-dev bash
```

Inside the container:

```bash
cd /workspace/wire-ethereum
npm ci
npx hardhat test src/test/outpost/Depositor.integration.ts
```

## Wire SysIO

Make sure the Wire submodules are present once on the host:

```bash
git -C wire-sysio submodule update --init --recursive
```

Bring up the local Wire node:

```bash
./local-compose.sh up wire-nodeop
```

That service now:

- builds the required `wire-sysio` targets inside Docker
- applies the local BoringSSL/OpenSSL pkg-config shim needed by this checkout
- runs `sys-util chain-configure`
- boots `kiod` and `nodeop` with the canonical 5-part `--signature-provider` format

If you want it detached:

```bash
./local-compose.sh up -d wire-nodeop
```

Check the node:

```bash
curl -s http://127.0.0.1:${WIRE_HTTP_PORT:-8887}/v1/chain/get_info -X POST
```

## Current Protocol Gap

From the code currently in this directory:

- Ethereum OPP is still epoch-based and sequential, but outbound epoch rollover no longer stalls on an unsubmitted prior epoch.
- Solana wire syndication is still mostly local-accounting plus admin completion hooks.
- The Solana PostLaunch withdraw path logs that it should send an OPP message, but does not do it yet.
- I do not see the inbound Wire-side OPP gate you described inside `wire-sysio` itself in this checkout.

That means the fastest path to a real end-to-end instant-swap test is:

1. Stand up the local Solana and Ethereum stacks above.
2. Use the existing wire-related Solana tests and OPP Ethereum tests as the starting harness.
3. Identify where the missing Wire-side depot / batch-operator logic actually lives if it is not in these repos.