Open-source library to normalize raw blockchain transactions (EVM calldata, Solana instructions, etc.) into a deterministic list of semantic actions. No judgments, no alerts, no AI.
- Converts raw inputs (EVM calldata, Solana instructions, logs) into
NormalizedAction[]. - Describes only the real actions that occurred in the transaction.
- Provides a standard action taxonomy and an extensible plugin framework.
npm install act-chainRepo name: act
npm package: act-chain
- ABI/log decoders: they decode, but do not produce a standardized action list.
- Transfer trackers: they cover only a narrow subset (e.g. ERC20/721/1155).
- Explainers/simulators: often add heuristics or UX layers; ACT stays neutral and deterministic.
- Chain-specific parsers: ACT targets multi-chain from day one with a shared action schema.
- No risk scoring.
- No human-readable explanations.
- No opaque heuristics.
- No AI.
import {
normalizeTx,
registerChainNormalizer,
registerActionDetector,
listSupportedActions,
} from "act-chain";
// 1) Register a chain normalizer
registerChainNormalizer("evm", evmNormalizer);
// 2) Register action detectors
registerActionDetector("TOKEN_TRANSFER", erc20TransferDetector);
registerActionDetector("TOKEN_APPROVAL", erc20ApprovalDetector);
// 3) Normalize a transaction
const actions = await normalizeTx(
{
chain: "evm",
txHash: "0x...",
calldata: "0x...",
logs: [/* receipt logs */],
},
{ includeRawRefs: true }
);
console.log(actions);
// 4) List supported actions
console.log(listSupportedActions());Input:
const tx = {
chain: "evm",
txHash: "0xabc...",
calldata: "0xa9059cbb...",
logs: [
{
address: "0xToken",
topics: [
"0xddf252ad...", // Transfer(address,address,uint256)
"0xFrom",
"0xTo",
],
data: "0x00000000000000000000000000000000000000000000000000000000000003e8",
logIndex: 12,
},
],
};Output:
[
{
action_type: "TOKEN_TRANSFER",
chain: "evm",
actors: {
from: "0xFrom",
to: "0xTo",
initiator: "0xFrom",
},
assets: [
{
asset_type: "token",
token_address: "0xToken",
token_standard: "ERC20",
},
],
amounts: [
{
asset_index: 0,
amount: "1000",
},
],
metadata: {
method: "transfer",
},
raw_refs: {
txHash: "0xabc...",
logIndex: 12,
},
},
];- Wallets: show on-chain actions without opinions.
- Explorers: standardize feeds and filters by action type.
- Analytics: unify metrics across chains.
- Simulators: build UIs for multi-action transactions.
- Add an action: implement a detector and register it.
- Add a chain: implement a chain normalizer.
- Extend metadata: use
metadatawith namespaced keys (e.g.protocol.uniswap.pool). - Extend metadata post-detection: register metadata extenders for an action type.
- Provide ABI hints: register an ABI resolver for a chain and decode calldata deterministically.
Neutrality, determinism, extensibility, and great DX. The library only answers: "What real actions occur in this transaction?"
- v0.1: EVM transfers + approvals
- v0.2: swaps + multicall
- v0.3: Solana
- v1.0: plugin ecosystem
ACT includes a tiny helper for common ERC20 selectors without external deps:
decodeErc20Transfer(calldata)decodeErc20Approval(calldata)decodeErc20Calldata(calldata)
You can register a resolver that returns known function signatures for a target address:
registerAbiResolver("evm", (address) => ["transfer(address,uint256)", ...])
Detectors can use this to gate calldata decoding without relying on external RPCs.
Plugins can expose a lightweight manifest for discovery and compatibility:
name,version,actVersion- optional
actions,chains,metadataExtenders
- On-chain activity is multi-chain, but action standards are fragmented.
- Developers need a neutral, deterministic layer before UI, analytics, or risk.
- An open, plugin-based action registry enables collaboration and coverage at scale.
/core
/chains/evm
/chains/solana
/actions
/plugins
/types
/tests
README.md
CONTRIBUTING.md
## Example input/output
Input:
```ts
const tx = {
chain: "evm",
txHash: "0xabc...",
calldata: "0xa9059cbb...",
logs: [
{
address: "0xToken",
topics: [
"0xddf252ad...", // Transfer(address,address,uint256)
"0xFrom",
"0xTo",
],
data: "0x00000000000000000000000000000000000000000000000000000000000003e8",
logIndex: 12,
},
],
};
Output:
[
{
action_type: "TOKEN_TRANSFER",
chain: "evm",
actors: {
from: "0xFrom",
to: "0xTo",
initiator: "0xFrom",
},
assets: [
{
asset_type: "token",
token_address: "0xToken",
token_standard: "ERC20",
},
],
amounts: [
{
asset_index: 0,
amount: "1000",
},
],
metadata: {
method: "transfer",
},
raw_refs: {
txHash: "0xabc...",
logIndex: 12,
},
},
];- Wallets: show on-chain actions without opinions.
- Explorers: standardize feeds and filters by action type.
- Analytics: unify metrics across chains.
- Simulators: build UIs for multi-action transactions.
- Add an action: implement a detector and register it.
- Add a chain: implement a chain normalizer.
- Extend metadata: use
metadatawith namespaced keys (e.g.protocol.uniswap.pool). - Extend metadata post-detection: register metadata extenders for an action type.
- Provide ABI hints: register an ABI resolver for a chain and decode calldata deterministically.
Neutrality, determinism, extensibility, and great DX. The library only answers: "What real actions occur in this transaction?"
- v0.1: EVM transfers + approvals
- v0.2: swaps + multicall
- v0.3: Solana
- v1.0: plugin ecosystem
ACT includes a tiny helper for common ERC20 selectors without external deps:
decodeErc20Transfer(calldata)decodeErc20Approval(calldata)decodeErc20Calldata(calldata)
You can register a resolver that returns known function signatures for a target address:
registerAbiResolver("evm", (address) => ["transfer(address,uint256)", ...])
Detectors can use this to gate calldata decoding without relying on external RPCs.
Plugins can expose a lightweight manifest for discovery and compatibility:
name,version,actVersion- optional
actions,chains,metadataExtenders
- On-chain activity is multi-chain, but action standards are fragmented.
- Developers need a neutral, deterministic layer before UI, analytics, or risk.
- An open, plugin-based action registry enables collaboration and coverage at scale.