@onchained/verify

Recover and independently verify an Onchained preservation from its Remount, Twin, or original ERC-721 contract and token ID. The token does not need an active mode. No gateway, indexer, Onchained API, private key, or historical log archive is used.

npx @onchained/verify <contract> <tokenId>

The contract may be:

• a live or restored Onchained Remount;
• a live or removed Onchained Twin; or
• the original ERC-721 contract, including a preserved token that never used either mode.

For an original token, the verifier first checks for an active Remount or Twin and verifies its pinned package. When no mode is active, it derives the token's canonical subject ID, reads the newest-first package list from PreservationDirectoryV1, surveys every admitted recognizer, reports every compatible candidate, and verifies the newest usable preservation. Package discovery does not depend on a factory.

With no RPC option, the command assumes Ethereum mainnet and fails over across three public RPC endpoints. The current Ethereum mainnet deployment is built in. Supply --rpc to use your own provider. A custom RPC may point to another EVM chain. The verifier reads and reports the chain ID returned by the RPC.

On another unlisted chain, provide the published directory explicitly with --directory.

ONCHAINED_RPC_URL may replace --rpc. The package intentionally does not support the superseded factory-era test deployment or its backingsOf/event- scan discovery path.

To save all recovered inputs and a machine-readable report:

npx @onchained/verify <contract> <tokenId> \
  --directory 0xPreservationDirectoryV1 \
  --out ./onchained-verification

The command:

1. authenticates the supplied or built-in directory;
2. validates its frozen recognizer membership and backing kinds;
3. derives each selected recognizer's capture and manifest registries;
4. recovers the exact tokenURI, package, metadata, image, and evidence bytes;
5. re-runs CID, UnixFS DAG/path, Arweave transaction/item/path proofs locally;
6. checks an active Remount or Twin's canonical factory binding and renderer;
7. reports Twin ownership synchronization state; and
8. reports HTTPS relationships as testimony, never cryptographic proof.

Large files automatically fall back from readFile to paged readStoredRange calls and local FastLZ decompression.

Restore IPFS pins

The restoration command verifies the preservation, reconstructs the original IPFS blocks, and writes one CARv1 file per IPFS-backed asset:

npx @onchained/verify restore-ipfs <contract> <tokenId> \
  --directory 0xPreservationDirectoryV1 \
  --out ./onchained-restoration

The CAR files and restoration details are written under ./onchained-restoration/ipfs/. Add --pin to import the CAR files and pin their blocks with a running local Kubo node. Use --ipfs-bin <path> when the Kubo executable is not named ipfs or is outside PATH.

Direct-CID and multiblock-file CARs contain the complete file DAG and receive a recursive root pin. A directory-path CAR is sparse. It contains the exact directory and HAMT nodes traversed by the original URI plus the complete terminal file DAG. The command directly pins those path nodes and recursively pins the terminal file. This keeps the preserved rootCID/path resolvable. Unrelated sibling subtrees are outside the preservation and cannot be restored.

Options

--rpc <url>               custom JSON-RPC endpoint
--directory <address>     PreservationDirectoryV1 on an unlisted chain
--out <directory>         save report, source bytes, and evidence
--pin                     import restored CARs and pin them with local Kubo
--ipfs-bin <path>         Kubo CLI executable used by --pin (default: ipfs)
--json                    print the complete JSON report
--verbose                 show RPC and protocol identifiers
--color                   always use terminal colors
--no-color                disable terminal colors
--require-cryptographic   fail if any relationship is HTTPS testimony
--page-bytes <number>     ranged-read page size (default 16384)
--timeout-ms <number>     RPC timeout (default 60000)

Library API

import { verifyOnchainedNft } from "@onchained/verify";

const report = await verifyOnchainedNft({
  contract: "0xOriginalOrModeContract",
  tokenId: 5030n,
  rpcUrl: "https://your-rpc.example",
});

A caller may instead supply a viem-compatible client. Verification and CAR export use read-only Ethereum calls. The optional --pin action changes only the configured local Kubo node.

What a pass means

PASS means the on-chain identity/linkage checks and every available source proof passed. An offline proof does not relabel an on-chain ATTESTATION as a VERIFICATION.

PASS_WITH_TESTIMONY means all checkable facts passed, but at least one asset uses HTTPS. No historical proof can establish what an HTTPS origin served.

The default terminal report is a concise user summary. It uses color when standard output is a terminal and honors NO_COLOR. Use --verbose for RPC, recognizer, observation, and discovery details. Use --json for the complete machine-readable report.

Development

npm install
npm test
npm run build
npm pack --dry-run

Before publishing, run the CLI from the checkout:

node dist/cli.js <contract> <tokenId> \
  --rpc https://your-rpc.example

The opt-in live suite can exercise the published Ethereum mainnet deployment:

ONCHAINED_LIVE_TESTS=1 \
ONCHAINED_LIVE_RPC_URL=https://0xrpc.io/eth \
ONCHAINED_LIVE_CASES='[{"contract":"0xfb21114b01468c3d8a9874b874493a0200809B63","tokenId":"3096","chainId":1,"families":[7,7],"verdict":"PASS_WITH_TESTIMONY"}]' \
npm run test:live

Set ONCHAINED_LIVE_DIRECTORY when the fixture uses an unlisted deployment.