test(token): native shielded token integration suite

[0xisk]

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update (if none of the other choices apply)

Fixes #??? — N/A, no tracking issue. See Relationship to other PRs below.

Adds the live-node integration suite for the native shielded token, together with
the two extensions it exercises. The standard's defining behaviors are
protocol-level (Zswap spend paths, color derivation, recipient privacy, coin
conservation, out-of-band delivery). A --skip-zk simulator cannot prove them;
the integration suite on the local stack is where the standard is actually
verified through the full prove → verify → apply loop.

What's here

• Supply extension — NativeShieldedTokenSupply (scalar) and
  NativeShieldedTokenFamilySupply (per-domain) over a shared
  NativeShieldedTokenSupplyCore, plus mocks, simulators, unit + property suites.
• Derived-nonce extension — NativeShieldedTokenDerivedNonce: counter-only
  derived coin nonces so callers need not manage nonces themselves; mock,
  simulator, unit suite.
• Integration suite — one deployable (NativeShieldedTokenV1) composing the
  Fungible token with both extensions, driven against the local stack
  (proof-server + indexer + node via make env-up):
  • testkit-free wallet/provider harness over the wallet-sdk, deploy +
    Zswap-effects decoders, a process-shared wallet pool;
  • specs: smoke, mint (both nonce paths), burn revert guards, supply accounting,
    shieldedMints reconstruction, recipient (un)linkability, duplicate-commitment
    rejection, unrestricted issuance;
  • new SDK devDependencies (midnight-js, wallet-sdk, ledger-v8, compact-js,
    @scure/bip39, pino) and compact:integration:net / test:integration:net
    scripts.

The network suite lives under test/integration/specs/nativeShieldedToken/** and
runs via test:integration:net. It is excluded from the default
test:integration (simulator) config, so it does not affect the existing
integration job.

Relationship to other PRs

This branch was rebased onto current main. The base standard (NativeShieldedToken
core) is already on main via #621. The supply and derived-nonce extension
sources are also proposed independently in #638 and #639 respectively; the
integration mock imports them, so they are carried here as prerequisites until
those land. Once #638/#639 merge, this branch rebases down to the integration
commit alone.

Verified locally

• compact compile (SKIP_ZK) of all token sources, extensions, mocks, and the
  NativeShieldedTokenV1 integration mock — clean against the current main core.
• tsc --noEmit — clean.
• biome check on all changed files — clean.

Not run in this environment: vitest execution (unit + network). The unit
suites run under CI's test job. The network suite needs yarn install (the new
SDK deps) and a live local stack (make env-up); it is verified by running
test:integration:net locally.

Out of scope (documented, not built)

Burn happy-paths, treasury Merkle spend, round-trip, and bypass-burn specs share
one root cause — the testkit-free wallet cannot yet import/spend a
contract-minted coin (no coin ciphertext is emitted; the facade has no coin-import
hook). Revert guards for these paths are covered. The unblock is a
coin-injecting shielded wallet supplied to WalletFacade.init.

PR Checklist

• I have read the Contributing Guide
• I have added tests that prove my fix is effective or that my feature works. See GUIDELINES.md#testing for more information.
• I have added documentation for new methods or changes to existing method behavior. See GUIDELINES.md#documentation for more information.
• CI Workflows Are Passing

Further comments

Opened as a draft: it carries the unmerged #638/#639 extension work, and the
network suite cannot go green in CI without the live stack. Mark ready once the
extension PRs land and the branch is rebased down to the integration commit.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: b68464d6-9520-43f8-92d0-d23f94ad6039

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch test/native-shielded-token-integration

---

_{Comment @coderabbitai help to get the list of available commands.}