From a7040e4c29244b28dff92f599fe1bc8e6035c292 Mon Sep 17 00:00:00 2001 From: John Saigle Date: Thu, 21 May 2026 07:28:12 -0400 Subject: [PATCH 1/4] docs(near): Add test instructions and overview --- near/README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/near/README.md b/near/README.md index be32d7b04f6..2d8dc11e75e 100644 --- a/near/README.md +++ b/near/README.md @@ -1,2 +1,98 @@ -welcome to wormhole on near +# Wormhole on NEAR + +## Building contracts + +Contracts are Rust crates compiled to WASM. Build them with: + +```sh +cd near +make build +``` + +This invokes `cargo build --target wasm32-unknown-unknown --release` for each contract +under `contracts/`. Requires the Rust toolchain specified in `rust-toolchain.toml` (1.63, +wasm32 target). + +To build via Docker (no local Rust needed): + +```sh +make artifacts +``` + +## Running tests locally + +The integration test (`near/test/test.ts`) exercises wormhole, token bridge, and NFT bridge +contracts against a local NEAR sandbox. It generates VAAs client-side using local guardian keys +from `testlib.ts` and exercises governance upgrades, attestations, transfers, and the +`ft_transfer_call` flow. + +### Prerequisites + +1. **Build the SDK** (the test imports from `@certusone/wormhole-sdk`): + ```sh + cd sdk/js + npm ci + npm run build-all # or: npm run build-deps && npm run build-lib + ``` + +2. **Build NEAR contracts** (required for the WASM files the test deploys): + ```sh + cd near + make build + ``` + +3. **Start a NEAR sandbox** locally: + ```sh + cd near + make nearcore # clones and builds nearcore from source (~10 min, one-time) + make run # starts sandbox on :3030, key server on :3031 + ``` + +4. **Run the test**: + ```sh + cd near + npm ci + make test + ``` + +> **Note:** The test makes a `getSignedVAAWithRetry` call against `localhost:7071` (a +> guardian spy). Without a guardian running, the test will fail at this step. +> A full Tilt devnet (`tilt up -- --near`) is the intended environment for end-to-end +> testing. + +## CI coverage + +| What | Where | Status | +|---|---|---| +| Contract compilation | `tilt` job (via `near/Dockerfile.deploy` → `build-contracts.sh`) | Runs on every PR | +| Contract deployment | `tilt` job (via `devnet/near-devnet.yaml` → `devnet_deploy.ts`) | Deploys wormhole, token bridge, nft bridge | +| Integration test (`test/test.ts`) | Not invoked anywhere | The test suite never runs in CI | +| Standalone build-only check | No dedicated job in `build.yml` | Not covered | + +The `tilt` job runs NEAR deployment by default in CI mode +(`near = cfg.get("near", ci)` in the root `Tiltfile`). This verifies contracts compile and +deploy, but runs no behavioral assertions. See `.github/workflows/build.yml` for the full +CI matrix. + +## Docker images + +| Dockerfile | Purpose | +|---|---| +| `Dockerfile.base` | Builds nearcore sandbox from source, creates base image `ghcr.io/wormhole-foundation/near:0.2` | +| `Dockerfile` | Production node image (pins the base image) | +| `Dockerfile.build` | Compiles contracts and exports WASM artifacts | +| `Dockerfile.contracts` | Bundles WASM files with deploy scripts | +| `Dockerfile.deploy` | Multi-stage: compiles contracts, then creates a deploy image with `devnet_deploy.ts` | + +## Contract layout + +| Contract | Path | Purpose | +|---|---|---| +| Wormhole core | `contracts/wormhole/` | VAA verification, guardian set management | +| Token bridge | `contracts/token-bridge/` | Cross-chain token transfers, attestations | +| NFT bridge | `contracts/nft-bridge/` | Cross-chain NFT transfers | +| NFT (wrapped) | `contracts/nft-wrapped/` | Wrapped NFT token implementation | +| Fungible token | `contracts/ft/` | Fungible token standard helpers | +| Mock bridge integration | `contracts/mock-bridge-integration/` | Test helpers for bridge integration | +| Mock bridge token | `contracts/mock-bridge-token/` | Test helpers for bridged tokens | From 5097678a3eaea39cb123e37957894a72dc5a66a4 Mon Sep 17 00:00:00 2001 From: John Saigle Date: Thu, 21 May 2026 09:45:13 -0400 Subject: [PATCH 2/4] spell --- cspell-custom-words.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/cspell-custom-words.txt b/cspell-custom-words.txt index 7cb57281011..c4063166cca 100644 --- a/cspell-custom-words.txt +++ b/cspell-custom-words.txt @@ -143,6 +143,7 @@ Monad moonscan moretags Neodyme +nearcore nhooyr obsv Obsv @@ -221,7 +222,9 @@ supermajority superminority tendermint Tendermint +Tiltfile terrad +testlib tokenbridge tokenfactory traceback From 7193b6a6eaed7c4cd8f50c3903cfe76b64fe665e Mon Sep 17 00:00:00 2001 From: John Saigle Date: Mon, 25 May 2026 07:20:07 -0400 Subject: [PATCH 3/4] mention some tests are encoded in the js sdk --- near/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/near/README.md b/near/README.md index 2d8dc11e75e..95da085f0c8 100644 --- a/near/README.md +++ b/near/README.md @@ -62,6 +62,8 @@ from `testlib.ts` and exercises governance upgrades, attestations, transfers, an ## CI coverage +See `.github/workflows/build.yml` for the full CI matrix. + | What | Where | Status | |---|---|---| | Contract compilation | `tilt` job (via `near/Dockerfile.deploy` → `build-contracts.sh`) | Runs on every PR | @@ -71,8 +73,7 @@ from `testlib.ts` and exercises governance upgrades, attestations, transfers, an The `tilt` job runs NEAR deployment by default in CI mode (`near = cfg.get("near", ci)` in the root `Tiltfile`). This verifies contracts compile and -deploy, but runs no behavioral assertions. See `.github/workflows/build.yml` for the full -CI matrix. +deploy. The tests under `sdk/js` perform some testing against NEAR. ## Docker images From 5f8b4c4aff111a8a50484d7fa0457938e9d8e9cd Mon Sep 17 00:00:00 2001 From: John Saigle Date: Wed, 22 Jul 2026 14:51:48 -0400 Subject: [PATCH 4/4] updates after running through commands --- cspell-custom-words.txt | 4 ++ near/README.md | 83 ++++++++++++++++++++++++++++------------- 2 files changed, 62 insertions(+), 25 deletions(-) diff --git a/cspell-custom-words.txt b/cspell-custom-words.txt index c4063166cca..0488cb3e5d5 100644 --- a/cspell-custom-words.txt +++ b/cspell-custom-words.txt @@ -112,6 +112,7 @@ kevm KEVM keymap keytool +killall klaytn Klaytn kompiled @@ -121,6 +122,7 @@ kujira Kujira lamports lastrun +libgit libp Linea Litecoin @@ -217,6 +219,7 @@ structs subdenom subdenoms Subdenoms +subshells suitypes supermajority superminority @@ -277,6 +280,7 @@ wormscanurl XFER xlayer xpla +zdiff XPLA XRPL Zellic diff --git a/near/README.md b/near/README.md index 95da085f0c8..4833aa0ecae 100644 --- a/near/README.md +++ b/near/README.md @@ -1,64 +1,98 @@ # Wormhole on NEAR +Unless stated otherwise, run each command block from the repository root. The +blocks use subshells so that one step does not change the working directory for +the next step. + ## Building contracts Contracts are Rust crates compiled to WASM. Build them with: ```sh -cd near -make build +(cd near && make build) ``` This invokes `cargo build --target wasm32-unknown-unknown --release` for each contract under `contracts/`. Requires the Rust toolchain specified in `rust-toolchain.toml` (1.63, wasm32 target). -To build via Docker (no local Rust needed): +To build via Docker (no local Rust needed), install and start Docker, then run: ```sh -make artifacts +(cd near && make artifacts) ``` +This writes the exported WASM files and checksums to `near/artifacts/`. The +pinned base image is currently `linux/amd64`, so Docker uses emulation on ARM +hosts. The first build downloads a large image and, because `near/` has no +`.dockerignore`, the build context can be several gigabytes when local build +outputs are present. + ## Running tests locally -The integration test (`near/test/test.ts`) exercises wormhole, token bridge, and NFT bridge -contracts against a local NEAR sandbox. It generates VAAs client-side using local guardian keys -from `testlib.ts` and exercises governance upgrades, attestations, transfers, and the -`ft_transfer_call` flow. +The integration test (`near/test/test.ts`) exercises the Wormhole core and token +bridge contracts against a local NEAR sandbox. It generates VAAs client-side +using local guardian keys from `testlib.ts` and exercises governance upgrades, +attestations, transfers, and the `ft_transfer_call` flow. NFT bridge coverage is +in the separate `near/test/nft.ts` script; `make test` does not run it. ### Prerequisites +Use Node.js from the repository's `.nvmrc`. Native sandbox builds additionally +require Rust via `rustup`, a C/C++ build toolchain, Git, Make, Python 3, and +`jq`. The pinned nearcore revision and its Rust 1.60 dependencies are known to +build on Linux/x86_64. The native build does not currently complete on Apple +Silicon; use the Tilt devnet described below on unsupported hosts. + 1. **Build the SDK** (the test imports from `@certusone/wormhole-sdk`): ```sh - cd sdk/js - npm ci - npm run build-all # or: npm run build-deps && npm run build-lib + (cd sdk/js && npm ci && npm run build-all) ``` + `npm run build-all` is equivalent to `npm run build-deps && npm run + build-lib`. npm 11 may warn that dependency install scripts have not been + approved; the SDK and NEAR builds currently complete despite those warnings. + 2. **Build NEAR contracts** (required for the WASM files the test deploys): ```sh - cd near - make build + (cd near && make build) ``` -3. **Start a NEAR sandbox** locally: +3. **Build and start a NEAR sandbox** locally on Linux/x86_64: ```sh - cd near - make nearcore # clones and builds nearcore from source (~10 min, one-time) - make run # starts sandbox on :3030, key server on :3031 + (cd near && make nearcore) # Clones and builds nearcore; allow at least 10 minutes. + (cd near && make run) # Runs the sandbox on :3030 and key server on :3031. ``` + Run `make run` in a dedicated terminal and leave it running while the test + executes. The current target calls `killall -q Python` before startup, which + can terminate unrelated Python processes. Do not use it on a shared host or + while other Python workloads are running; prefer Tilt in those environments. + + If `make nearcore` fails after creating `near/nearcore/`, Make considers the + directory complete and a retry only reports `nearcore is up to date`. + Remove the partial `near/nearcore/` directory before retrying. Cargo 1.60's + bundled libgit2 can also reject newer Git configuration values such as + `merge.conflictStyle=zdiff3`; use an isolated build environment with + compatible Git defaults or use Tilt rather than changing user-wide Git + settings. + 4. **Run the test**: ```sh - cd near - npm ci - make test + (cd near && npm ci && make test) ``` -> **Note:** The test makes a `getSignedVAAWithRetry` call against `localhost:7071` (a -> guardian spy). Without a guardian running, the test will fail at this step. -> A full Tilt devnet (`tilt up -- --near`) is the intended environment for end-to-end -> testing. +The test first reads `validator_key.json` from the key server on +`localhost:3031`, so it fails immediately if the sandbox is not running. Later, +it calls `getSignedVAAWithRetry` against the guardian spy on `localhost:7071` +and fails if no guardian is running. + +For full end-to-end testing, use the intended Tilt environment instead of the +native sandbox commands: + +```sh +tilt up -- --near +``` ## CI coverage @@ -96,4 +130,3 @@ deploy. The tests under `sdk/js` perform some testing against NEAR. | Fungible token | `contracts/ft/` | Fungible token standard helpers | | Mock bridge integration | `contracts/mock-bridge-integration/` | Test helpers for bridge integration | | Mock bridge token | `contracts/mock-bridge-token/` | Test helpers for bridged tokens | -