Agnostic data decoding: EVM ABIs and Stellar Formats

Record Formats and Decoder Inputs

A raw record's format determines the decoder and its inputs; ABI-encoded contract parameters also require the applicable ABI. Agnostic's ch-stellar includes stellar_xdr_decode and stellar_strkey_decode for Stellar formats. XDR, or External Data Representation, encodes ledger and transaction structures; StrKey represents addresses and other identifiers. The corresponding installed function must support the input's type and representation.

Agnostic's EVM toolset also lists evm_decode_call for calls and ethereum_decode_tx for transaction parsing. Serialized transaction bytes concern the enclosing transaction format; ABI decoding concerns contract parameters within a call. For successful ABI calls, return data uses the function's output types. Revert data may encode an error and its parameters. Transaction envelopes, call inputs, call outputs, and event logs therefore require distinct interpretations. For an event, supply its topics and data alongside candidate event descriptions. Successful event decoding exposes the matched signature and parameter values in the function's response.

Selectors and ABI Descriptions

ABI descriptions identify parameter types and their order; event descriptions also specify which arguments use topics.

Function Selectors

An ABI function selector consists of the first four bytes of the Keccak-256 hash of its canonical signature. Calldata then carries encoded arguments. Return types do not participate in that selector. Different function signatures can share selector bytes, so a lookup can yield several candidates. The called contract's interface and argument layout determine which candidate applies. A selector match alone does not establish the contract's identity or the meaning of its parameters.

Event Fullsigs

An event's canonical signature captures its name and parameter types, leaving out the indexed modifiers. Agnostic's fullsig descriptions retain indexed placement so the event decoder can separate topic values from data values. Two event declarations can share a canonical signature while assigning indexed parameters differently. A signature dictionary can supply several candidate descriptions, while the emitting contract's ABI establishes which declaration applies. Keep each candidate associated with the contract interface it represents.

The Go event interface also accepts references to JSON ABI documents as decoder inputs. A fullsig keeps its declaration directly in the query. A remote ABI document introduces a retrieval dependency: document reachability and contents affect which descriptions the decoder can obtain. This option belongs to the Go interface; availability in another build depends on that build's supported decoder inputs.

Hex Text and Binary Arguments

Hexadecimal text and raw bytes are different representations even when they describe the same payload. The Go event interface expects topics as Array(FixedString(32)), event data as String, and decoder descriptions as Array(String). The 32 specifies bytes in each binary topic, rather than printed characters. Agnostic's evm_hex_decode converts hexadecimal input before decoding; a type cast alone does not convert its characters into raw bytes. Columns already storing binary strings do not need that conversion. Preserve topic order because indexed parameter positions follow that order.

Validate topic lengths before forcing a fixed-width type, because ClickHouse can pad shorter strings with null bytes.

Decoded Values and Execution Context

A successful decode interprets the supplied bytes under the chosen ABI; transaction execution and contract identity require their own context.

Result Structure

The Go evm_decode_event interface returns a JSON Result envelope, with decoded fields inside value. Its signature field identifies the matched event signature, and inputs holds the parameters. Unnamed arguments can appear under positional keys such as arg0. Agnostic's Rust-based ch-evm also includes event decoding. Its JSON interface can differ from the Go implementation, so extraction expressions must fit the installed response. Inspect the decoded object before converting its parameters into persistent columns, preserving any decoding error separately from successful values.

Integer Values and Record Identity

Decoded integers may appear as decimal strings in JSON. Preserve their exact values until the query chooses a compatible numeric type. ClickHouse's UInt256 can represent an ABI uint256 value, while UInt64 cannot cover that full range. Signed parameters require signed interpretation. Floating-point conversion can lose integer precision. SQL queries can use extracted fields to filter or group records, with measurement units coming from the contract's meaning.

Keep the network, contract address, block reference, and transaction or log position beside decoded fields. Proxy upgrades can change the implementation a stable address uses, so historical rows may need historical ABI context. Calldata describes the supplied function and arguments; it does not prove execution completed successfully. A transaction receipt's status records the overall transaction outcome when that field exists. The receipt's status, decoded input parameters, and returned output values describe different parts of the interaction.

Can an Indexed String Be Recovered From Its Topic?

An indexed ABI string parameter contributes a Keccak-256 hash of its special in-place encoding to the log topic; the topic alone cannot recover the original text. Arrays, dynamic bytes, and tuples also have hashed indexed representations. A contract can expose the text by emitting it in a non-indexed parameter as well. A complete ABI explains that layout; it cannot supply plaintext the event omits. Access to a readable copy depends on the data the contract actually emits.

---

Correcting an Event Description's Indexed Placement

A mismatched indexed modifier changes where a decoder expects to find an event parameter. Consider a hypothetical, complete log from a non-anonymous event with an indexed address parameter and a non-indexed uint256 parameter. Assume the applicable contract ABI confirms this layout and the Go event decoder is installed. The selected dictionary entry omits the address parameter's indexed modifier.

The first decode fails because its description expects both values in the data payload. Correct the event declaration to mark the address as indexed, then pass the unchanged topics, data, and corrected candidate to evm_decode_event.

The corrected call returns a decoded value containing the event signature and an inputs object. The address now comes from its topic, and the integer comes from data. Comparing these fields with the known ABI confirms the intended parameter order. The corrected description applies to this log's layout.

View image file

An upgrade changing this event's indexed placement would invalidate the description for new logs. Associate the corrected entry with the contract and block range its ABI covers. Historical logs retain their earlier layout even if a later implementation changes the event declaration.

Installed UDFs and Prepared Columns

Decoder availability depends on the functions registered in the connected ClickHouse environment. An executable UDF configuration declares its command, argument types, return type, and data exchange format. Agnostic distributes binaries with registration files and SQL functions in bundles. Its Go and Rust implementations can differ in data transport and result structure. Keep the binary and function configuration from the same implementation together. An installed function name alone does not establish the arguments or output format its binary expects.

Prepared event and call collections already expose decoded parameter columns. Agnostic's v1 event schema combines parameter position and derived type in input column names; its v1 call schema also has output columns. Those collections provide a stored representation, while decoder functions interpret raw payloads during a query. Existing decoded fields suit analysis when their ABI context and types fit the question. Retaining raw bytes permits later reinterpretation when a description changes or a stored representation lacks a needed field.