ArcReady

Arc-specific static CI quality gate and integration-pattern validator for wallets, bridges, App Kit integrations, and dApps.

ArcReady helps developers catch common Arc integration mistakes before release. It is a developer-side early warning layer for static checks in local workflows and CI.

ArcReady is an independent open-source project. It is not an official Circle or Arc product.

Release boundary: npm latest is the reviewed arcready@0.4.0 package. The current stable Action tag remains tanka420/arcready@v0.3.0 until the staged v0.4.0 Action proof and immutable tag checkpoints complete. The v0.3 Action wrapper can run the new package by setting arcready-version: "0.4.0".

What It Is

ArcReady scans source files for common Arc-specific integration assumptions across three presets:

• wallet
• bridge
• app-kit

It reports findings in terminal, JSON, Markdown, or HTML formats and can fail CI based on critical, warning, info, or none thresholds.

Quick Demo

npx --yes arcready@0.4.0 init
npx --yes arcready@0.4.0 scan

CI-oriented Markdown report:

npx --yes arcready@0.4.0 scan --format markdown --out arcready-report.md

Shortened example output:

ArcReady v0.4.0
Project: my-arc-app
Score: 75
Status: fail
Summary: 1 critical, 0 warning, 0 info

Reproducible Before/After Demo

From a repository checkout, install the locked dependencies and run the checked-in broken/fixed demo pair:

corepack pnpm install --frozen-lockfile
corepack pnpm demo:fixtures

This command scans only broken-arc-integration followed by fixed-arc-integration. The broken project must demonstrate wallet/ARC_CHAIN_METADATA, wallet/NO_BLOB_TX_ON_ARC, bridge/CCTP_DOMAIN_26, and app-kit/APPKIT_CHAIN_IDENTIFIER_VALID. The fixed project must finish with status pass, score 100, and zero findings.

This is a deterministic static-analysis demonstration of those checked-in patterns, not universal Arc compatibility or runtime verification.

Quick Start

Run without installing:

npx --yes arcready@0.4.0 scan

Create a config file:

npx --yes arcready@0.4.0 init

Install locally:

npm install -D arcready
npx arcready scan

GitHub Action

Minimal workflow:

name: ArcReady

on:
  pull_request:
  push:
    branches: [main]

jobs:
  arcready:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - uses: actions/checkout@v4

      - uses: tanka420/arcready@v0.3.0
        with:
          arcready-version: "0.4.0"
          fail-on: critical

The stable v0.3.0 Action wrapper defaults to npm package v0.3.0, so the example pins its package input to the published v0.4.0 release. The repository Action candidate defaults to v0.4.0, but no v0.4.0 Action tag is claimed until the separate exact-SHA proof and tag checkpoints complete.

with:
  arcready-version: "0.4.0"

See docs/github-action.md for inputs, artifact behavior, and external usage notes.

What ArcReady Checks

Wallet

• Arc chain metadata
• native USDC display
• avoiding ETH gas labeling assumptions
• one-confirmation finality assumptions
• unsupported PREVRANDAO assumptions
• blob transaction assumptions

Bridge

• one-confirmation bridge assumptions
• CCTP domain 26
• canonical USDC vs wrapped USDC assumptions
• relayer gas token assumptions
• retryable CCTP attestation 404 handling
• avoiding PREVRANDAO relay selection assumptions

App Kit

• Arc_Testnet / Arc chain identifier usage
• capability guardrails
• explicit RPC configuration
• user-controlled wallet delegate handling
• user-facing fee explanation
• bridge minimum amount copy

ArcReady checks static integration patterns. It does not validate the Circle SDK or App Kit at runtime.

Example Output

CRITICAL (1)

- wallet/ONE_CONFIRMATION_FINAL
  Message: Arc wallet transaction flow appears to wait for more than one confirmation.
  Files: src/wallet.ts
  Suggested fix: Set Arc confirmation waits and release logic to 1 confirmation.

Reports

Supported formats:

• terminal
• JSON
• Markdown
• HTML

npx --yes arcready@0.4.0 scan --format terminal
npx --yes arcready@0.4.0 scan --format json --out arcready-report.json
npx --yes arcready@0.4.0 scan --format markdown --out arcready-report.md
npx --yes arcready@0.4.0 scan --format html --out arcready-report.html

Generated report folders such as .arcready/ and reports/ are ignored by git.

Experimental canonical JSON output

Use the explicit opt-in canonical projection:

arcready scan --json-v2

This leaves the default legacy output unchanged and emits the exact ScanResultV2 document, versioned by contractVersion:

{
  "contractVersion": "2.0",
  "coverage": { ... },
  "findings": [ ... ],
  "diagnostics": [ ... ]
}

The experimental runtime currently executes exactly four rules in stable order: bridge/CCTP_DOMAIN_26, bridge/NO_WRAPPED_USDC_ON_ARC, bridge/RELAYER_USES_USDC_FOR_GAS, and wallet/ARC_CHAIN_METADATA. The JSON exposes selectedOccurrences: 4, while the selected rule IDs remain a private runtime tuple. Analysis and applicability remain unknown. Exit code 0 means a valid document was produced, not that the repository is compatible: findings and recoverable diagnostics are observational, and canonical enforcement is deferred.

What ArcReady Does Not Do

ArcReady does not perform:

• live Arc RPC checks
• Circle API checks
• on-chain transaction simulation
• contract deployment validation
• bridge runtime simulation
• real App Kit runtime validation
• SaaS/dashboard monitoring

It is a static CI quality gate, not a runtime verifier or compatibility guarantee.

Why This Exists

Arc is EVM-compatible, but Arc integrations should not blindly inherit Ethereum-default assumptions. Teams can accidentally ship incorrect gas labels, finality waits, CCTP domain values, wrapped asset assumptions, or App Kit configuration mistakes.

ArcReady turns those common integration risks into local and CI checks.

Configuration Basics

Create arcready.config.json in the project you want to scan:

{
  "presets": ["wallet", "bridge", "app-kit"],
  "paths": ["src", "app", "components", "lib", "package.json"],
  "exclude": ["dist/**", "coverage/**", ".next/**", "node_modules/**"],
  "reporters": ["terminal", "json", "markdown", "html"],
  "failOn": "critical",
  "rules": {
    "wallet/ONE_CONFIRMATION_FINAL": "critical",
    "bridge/BRIDGE_CONFIRMATIONS_ONE": "critical",
    "app-kit/APPKIT_CHAIN_IDENTIFIER_VALID": "critical"
  }
}

CI Behavior

failOn controls when the CLI exits non-zero:

Value	Behavior
critical	Fail only when critical findings exist
warning	Fail when warning or critical findings exist
info	Fail when any finding exists
none	Never fail due to findings

The CLI --fail-on option overrides the config value.

Presets

Preset	Focus	Example rules
wallet	Wallet UX, chain metadata, fee display, finality	ARC_CHAIN_METADATA, WALLET_NATIVE_USDC_DISPLAY, ONE_CONFIRMATION_FINAL
bridge	CCTP, finality, relayer gas, canonical USDC	BRIDGE_CONFIRMATIONS_ONE, CCTP_DOMAIN_26, RELAYER_USES_USDC_FOR_GAS
app-kit	App Kit chain identifiers, RPC configuration, Unified Balance checks	APPKIT_CHAIN_IDENTIFIER_VALID, APPKIT_CUSTOM_RPC_RECOMMENDED, UB_DELEGATE_REQUIRED, UB_FEE_EXPLANATION_PRESENT

The deprecated APPKIT_CAPABILITY_SUPPORTED and APPKIT_BRIDGE_MIN_AMOUNT_NOTE rule objects remain programmatically available for compatibility, but the default App Kit preset excludes them because their current contracts are unsupported or contradicted by official evidence. This focused exclusion does not apply the taxonomy catalog's other default-policy recommendations at runtime.

The deprecated wallet/NO_ETH_GAS_LABEL heuristic is also excluded from the default Wallet preset. It can be enabled explicitly at info, warning, or critical for human review, but its file-level text match does not prove that the matched ETH/Gwei text is rendered, Arc-owned UI copy.

Full rule list: docs/rule-catalog.md

Demo projects: use the broken Arc integration and fixed Arc integration as before/after states for a static repair workflow.

Validation Fixtures

ArcReady includes good and bad fixtures for wallet, bridge, and App Kit integrations:

corepack pnpm validate:fixtures

Good fixtures should pass with zero findings. Bad fixtures should produce findings and fail according to their expected result.

Contributing

Contributions should keep ArcReady focused and conservative:

• keep rules Arc-specific
• prefer precise findings over noisy checks
• add or update tests for rule or message changes
• keep reporter schemas and CLI behavior stable unless a task explicitly changes them
• do not add SaaS, dashboard, auth, database, telemetry, or runtime validation features

Development commands:

corepack pnpm build
corepack pnpm test
corepack pnpm lint
corepack pnpm validate:fixtures

Independent Disclaimer

ArcReady is an independent open-source project. It is not an official Circle or Arc product, and its static findings should be treated as developer-side release checks rather than official validation.

License

MIT