OpenScan AI

Modular, TypeScript-first system for on-chain blockchain analysis. Built on top of @openscan/network-connectors.

Packages

Package	Description
@openscan/utils	Zero-dep utilities: hex, units, address validation, ABI, events, signatures, tx-analysis (call trees, prestate diffs, contract enrichment)
@openscan/algorithms	On-chain algorithms: tx history, token balance, gas price
@openscan/cli	CLI tool (openscan) wrapping algorithms and utils
@openscan/skills	Markdown-based procedural knowledge for AI agents (skills.sh format)
@openscan/adapters-langchain	LangChain tool wrappers
@openscan/adapters-openclaw	OpenClaw adapter

Setup

pnpm install
pnpm build

CLI Usage

After pnpm build, invoke the CLI via node packages/cli/dist/bin.js <command> (or link the openscan bin).

analyze-tx <txHash>

High-level transaction debugger. Wraps analyzeTx from @openscan/utils to fetch the call tree, prestate diff, raw structLogs trace, and contract metadata in one pass. Requires an RPC that supports debug_traceTransaction (e.g., Alchemy) — falls back per-section with { data: null, error: "not supported" } when a tracer isn't available.

# Defaults: call tree + contracts
openscan analyze-tx 0x<txHash> --chain 1 --alchemy-key "$ALCHEMY_API_KEY"

# Full: add prestate diff and raw trace, enrich contracts via Etherscan
openscan analyze-tx 0x<txHash> --chain 1 --alchemy-key "$ALCHEMY_API_KEY" \
  --include-prestate --include-raw-trace --etherscan-key "$ETHERSCAN_API_KEY"

Flags: --include-prestate, --include-raw-trace, --skip-call-tree, --skip-contracts, --etherscan-key (or ETHERSCAN_API_KEY env var).

Result includes verificationLinks pointing at https://openscan.eth.link/#/:chainId/tx/:txHash.

Testing

Run all tests

pnpm test

Run tests for a specific package

pnpm --filter @openscan/utils test
pnpm --filter @openscan/algorithms test
pnpm --filter @openscan/cli test
pnpm --filter @openscan/adapters-langchain test
pnpm --filter @openscan/adapters-openclaw test

Run a single test file

pnpm --filter @openscan/utils exec tsx --test tests/hex.test.ts

Type checking

pnpm typecheck

Linting and formatting

pnpm lint
pnpm format:fix
pnpm lint:fix

Publishing

Packages use changesets for independent versioning.

1. Create a changeset

pnpm changeset

Follow the prompts to select which packages changed and the semver bump type (patch, minor, major). This creates a changeset file in .changeset/.

2. Version packages

pnpm changeset version

This consumes all pending changesets, bumps versions in each package's package.json, and updates changelogs.

3. Build

pnpm build

4. Publish to npm

pnpm changeset publish

This publishes all packages with new versions to npm. Each package has "publishConfig": { "access": "public" } configured.

Publish a single package manually

pnpm --filter @openscan/utils exec npm publish --access public

Dry run (preview what would be published)

pnpm --filter @openscan/utils exec npm publish --access public --dry-run