Add local instaswap E2E workspace harness

LOCAL-E2E.md

@@ -0,0 +1,187 @@
+# 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.