The pipeline accepts standard Solidity ABI JSON files. Only event and function entries are used - all other entry types (constructor, fallback, receive) are ignored.
[
{
"type": "event",
"name": "Transfer",
"inputs": [
{ "name": "from", "type": "address", "indexed": true },
{ "name": "to", "type": "address", "indexed": true },
{ "name": "value", "type": "uint256", "indexed": false }
]
},
{
"type": "function",
"name": "transfer",
"stateMutability": "nonpayable",
"inputs": [
{ "name": "to", "type": "address" },
{ "name": "amount", "type": "uint256" }
]
}
]
- Block explorers (Etherscan, Basescan) under the “Contract” tab
- Solidity compiler output (
artifacts/ directory)
- The
cast interface command from Foundry
You can combine multiple contract ABIs into a single file. The decoder uses event signature hashes and function selectors for matching, so entries from different contracts do not conflict as long as names are unique.
Solidity Type Mapping
| Solidity Type | Column Type | Notes |
|---|
address | STRING | Hex-encoded, checksummed |
uint8 through uint256 | STRING | Full precision as decimal strings |
int8 through int256 | STRING | Full precision as decimal strings |
bool | BOOLEAN | |
bytes | STRING | Hex-encoded with 0x prefix |
bytes1 through bytes32 | STRING | Hex-encoded with 0x prefix |
string | STRING | |
tuple | JSON | JSON-serialized object |
Arrays (e.g., uint256[]) | JSON | JSON-serialized array |
All integer types are stored as decimal strings to preserve full precision. Solidity uint256 values can exceed the range of 64-bit integers, so string representation avoids truncation.
Contract Address Filtering
When contract_addresses is specified in the ABI config, only matching records are decoded:
| Decoding Mode | Filter Field | Description |
|---|
| Event decoding | contract_address | The contract that emitted the event |
| Function decoding | to_address | The contract that was called |
unmatched strategy.
Unmatched Records
When a log or transaction does not match any ABI signature (either because it’s from a non-matching contract or because the signature is not in the ABI file):
unmatched Setting | Behavior |
|---|
skip (default) | Drop the record silently |
raw_table | Write to raw_logs or raw_transactions table with original columns intact |
raw_table when you want to capture all records and handle unmatched ones separately in your downstream processing.
Configuration Reference
abi:
path: "/etc/pipeline-api/abi.json"
contract_addresses:
- "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45"
- "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
unmatched: "skip"
| Field | Type | Required | Default | Description |
|---|
path | string | yes | - | Path to ABI JSON file |
contract_addresses | list | no | all | Contract address whitelist. Decodes all contracts when empty. |
unmatched | string | no | skip | How to handle records that don’t match any ABI signature |
Validation
The pipeline validates ABI configuration at startup:
- ABI file must exist and be valid JSON
- ABI file must contain at least one
event or function entry relevant to the topic entity
- ABI decoding is only compatible with
logs and transactions topic entities
- ABI decoding is incompatible with the Kafka (raw) destination type
- Output table names from ABI entries must not collide with each other or with normalizer output tables
If validation fails, the pipeline will not start. Check the error message in the GoldRush Platform dashboard for details on which validation check failed.
