crosschain-incident

A read-only cross-chain incident normalizer. Feed it an operator-supplied JSON export of source/destination message status; get back a conservative evidence report with PASS / FAIL / UNKNOWN findings. An offline formatter, not a live tracer.

What it is

crosschain-incident is a command-line tool that normalizes an operator-supplied export of cross-chain message status into one consistent incident report. It does not connect to any chain or bridge protocol — it normalizes the JSON you already have. Missing or ambiguous fields stay UNKNOWN; nothing is guessed.

The problem it solves

Bridge and interoperability operators emit status payloads in inconsistent shapes. crosschain-incident answers: normalize different bridge status payloads into one incident postmortem format. It gives you a single, conservative report of what the export says — source delivered, destination failed, and so on — without inventing data.

When to use it

• You have a cross-chain message status export (source/destination) and want a standardized incident report.
• You want missing fields preserved as UNKNOWN rather than silently assumed.
• You need a machine-readable findings[] (exit 1 on a flagged failure like DESTINATION_FAILED).

When NOT to use it

• You want to trace a bridge live, detect replay attacks, or flag anomalous transfers in real time — it is an offline formatter, not a monitor.
• You want it to query LayerZero, Hyperlane, or any protocol API — those adapters are roadmap, not implemented.
• You want retries, refunds, or message submissions — it only normalizes your export.

Installation

npm install -g crosschain-incident     # or run without installing:
npx crosschain-incident inspect --input ./message.json --json

Real command

npx crosschain-incident inspect --input ./message.json --json

Example input (documented shape)

This is the example payload from the published README — a LayerZero source/destination status export.

{
  "protocol": "layerzero",
  "messageId": "example-id",
  "source": { "status": "delivered", "network": "source-chain", "tx": "0x...", "observedAt": "2026-01-01T00:00:00Z" },
  "destination": { "status": "failed", "network": "destination-chain", "tx": "0x...", "observedAt": "2026-01-01T00:00:10Z" }
}

Example output

Representative normalized report. The tool flags failures like DESTINATION_FAILED as machine-readable findings (exit 1); missing fields stay UNKNOWN.

{
  "protocol": "layerzero",
  "messageId": "example-id",
  "findings": [
    { "status": "FAIL", "code": "DESTINATION_FAILED", "message": "destination status is failed" }
  ],
  "status": "FAIL"
}

What it does

• Normalizes source / destination / delivered / failed / unknown / source-only / destination-failed states.
• Missing or ambiguous fields stay UNKNOWN — nothing is guessed.
• Flags failures like DESTINATION_FAILED as machine-readable findings (exit 1).
• Handles invalid JSON and UTF-8 BOM input without crashing.

What it does NOT do

• Does not query LayerZero, Hyperlane, or any protocol API yet — it normalizes your export.
• No retries, refunds, or message submissions.
• Not an online cross-chain monitor — protocol adapters are the roadmap.

Limitations

• Its accuracy is bounded by the export you provide; it cannot discover status it was not given.
• Experimental (0.1.0): local state-fixture tests pass (delivered, destination-failed, invalid JSON, BOM JSON). No real protocol API validation yet.

Status

Experimental (0.1.0). Local state-fixture tests pass (delivered, destination-failed, invalid JSON, BOM JSON). No real protocol API validation yet.

npm

Package: crosschain-incident — published by npm user eidonze, version 0.1.0, MIT.

GitHub

Source: xka0085-byte/crosschain-incident — issues and the full README live there.

Related tools

• wallet-evidence — the suite's Solana transaction evidence CLI; both verify event/chain facts on different layers.
• mcpdoctor — the suite's MCP/x402 endpoint inspector.
• ReceiptRail — on-chain x402 delivery receipts.

Part of the Agent / Chain Evidence Tools suite · MIT · Node ≥ 18 · read-only, offline formatter