Polymer Testnet + IBC Preflight Guard

Catch unsafe cross-chain configuration before installing dependencies, going online, or signing a transaction.

IBC Preflight Guard is a zero-runtime-dependency Node.js CLI for EVM IBC-style testnet workflows. Its first compatibility profile protects this repository's Polymer/vIBC Base Sepolia to Optimism Sepolia example. The scanner is local and offline by default: it parses JSON and .env files without executing project configuration, prints only variable names, and never sends or persists secret values.

Status: early-stage v0.1.0. This repository originated from the open-ibc Solidity template. TOPPOOL maintains the preflight security layer, tests, CI, documentation, and compatibility work here. The included 2024 vIBC workflow is a legacy/testnet profile, not a claim that it represents Polymer's current recommended architecture.

Why it exists

Cross-chain testnet scripts combine private keys, RPC calls, contract addresses, channel/client identifiers, mutable JSON, shell commands, and third-party dependencies. One placeholder address or client/channel mismatch can waste a deployment; an unsafe config path can cross a trust boundary before a transaction is signed.

Existing _sanity-check scripts run after deployment and query chain state. IBC Guard runs earlier and offline, including before npm install:

node bin/ibc-guard.js check --allow-sim-client

A fresh template intentionally fails until its deployment values are real:

IBC003 ERROR config.json:/sendPacket/optimism/portAddr Placeholder or zero EVM address
IBC004 ERROR config.json:/sendUniversalPacket/optimism/channelId Invalid or placeholder channel ID: channel-x
IBC007 WARNING config.json:/proofsEnabled Simulation client is enabled; packets are not proof-secured

The process exits 0 when no blocking finding exists, 1 for findings, and 2 for invalid input or usage.

Checks in v0.1.0

Rule	Protects against
IBC001	malformed or incomplete config/registry structure
IBC002	unknown or identical source/destination networks
IBC003	invalid, zero, or template-placeholder EVM addresses
IBC004	invalid and placeholder channel identifiers
IBC005	unsafe timeout types and optional project timeout policy
IBC006	non-boolean universal/proof mode flags
IBC007	proof/client/universal-channel mismatch and sim-client trust
IBC008	missing or malformed local signing key without value disclosure
input error	config path traversal, executable config, and symlink escape (exit 2)
IBC011	review warnings for recursive deletion and child processes
IBC013	unverified custom proof-mode flow (blocked) and known dummy-proof simulation paths

Output for humans and CI

# Human-readable report
node bin/ibc-guard.js check --allow-sim-client

# Stable JSON for automation
node bin/ibc-guard.js check --format json --allow-sim-client

# SARIF 2.1.0 for code-scanning systems
node bin/ibc-guard.js check --format sarif --allow-sim-client > ibc-guard.sarif

# CI-safe repository scan without local credential readiness
node bin/ibc-guard.js check --skip-env --allow-sim-client

# Treat every warning as blocking; warn above a project policy
node bin/ibc-guard.js check --strict --max-timeout 36000

See the full CLI and security model.

Run the tests

No package installation is required for the guard or its tests:

npm test
# or: node --test test/ibc-guard.test.js

The suite covers safe and malicious fixtures, stable rule IDs, path escape, bad JSON, exit codes, SARIF structure, and secret redaction across all reporters.

Original Solidity example

The repository still contains the original XCounter contracts and legacy Polymer/vIBC automation for Base and Optimism Sepolia. Those flows need Node 18+, Foundry, just, external testnet services, and a local .env. They should be treated as experimental testnet infrastructure. Run the offline guard and review current upstream documentation before any signed transaction.

Roadmap

• Add operation-specific deploy, channel, and send policy gates around existing checks.
• A current Polymer Prove API/CrossL2Prover manifest profile.
• GitHub code-scanning upload and reusable workflow examples.
• Compatibility fixtures contributed by other EVM/IBC projects.

Roadmap items are plans, not shipped features. Please open an issue with a minimal, secret-free fixture if a network or workflow should be supported.

Contributing and security

Read CONTRIBUTING.md, the threat model, and SECURITY.md. Do not attach private keys, API tokens, live .env files, or sensitive RPC URLs to issues. All generated or automated changes require human maintainer review before merge or release.

License and provenance

New IBC Guard code is MIT-licensed. The repository derives from the open-ibc template; provenance and inherited licensing uncertainty are documented in NOTICE. Files that retain SPDX-License-Identifier: UNLICENSED are not relicensed by the new MIT license and remain excluded from the licensed guard distribution until their provenance is resolved.