Turn transactions into reliable data

Define the output before writing another parser. If the reader of your data needs a position, specify what creates, changes and closes that position. If they need a swap, specify which execution details make up one swap and which other transfers must be kept separate.

Keep these layers connected through stable identifiers. A dashboard discrepancy should be traceable to the underlying transaction and the transformation version. If the raw record is too large to duplicate in every row, retain a durable reference to its source.

The Substreams Solana NFT example uses exchange-specific decoding functions. It illustrates a useful boundary: sharing a chain does not mean that every protocol expresses its business activity through the same schema.

Look for a suitable module before implementing extraction and decoding from scratch. Substreams foundational modules provide reusable transformations and filtering primitives. Their value depends on how well the particular module covers your network, protocol version and required output.

Review the actual package and source rather than relying on a familiar name. Confirm the network configuration, starting history, parameters, output schema, available documentation and licence. Record the version you choose so that a future update is a deliberate decision.

Classify the fit

• Use directly: the module already produces the data contract your application requires.
• Compose: the module decodes useful inputs, and your own module adds domain-specific interpretation.
• Extend or replace: required instructions, protocol versions or fields are missing.

A source repository and a published package are different delivery states. Check how the dependency is obtained and built. Avoid a workflow in which production depends on an undocumented local copy that another developer cannot reproduce.

Stable dependencies also make performance observations easier to interpret. If a package or dependency changes the effective module hash, previously cached execution may no longer apply. Record that change separately from changes to the business schema.

Choose identifiers from the source model. On Ethereum, log records expose transaction and block identities as well as log position. Preserve enough of that context to order and investigate the decoded events. For a dataset spanning several networks, include the chain identifier in the identity design.

Solana's RPC structures distinguish transaction instructions from inner instructions created through cross-program invocation. Their parent instruction index and execution context matter when reconstructing activity. A decoder that only reads the top-level instruction list can have a narrower scope than the application expects.

These fields are a proposed modelling checklist, not one universal schema for all chains. A multi-chain table should preserve differences that matter instead of forcing unrelated execution models into a single ambiguous event index.

Once a record is decoded, decide how it changes the model. A field called amount needs a unit. A balance needs an owner and a point in time. A price needs a source and a timestamp. Preserve the original quantities alongside conversions so that rounding or metadata changes remain explainable.

Specify the transformation rules

• Which events or state observations create and update each entity?
• In what order must changes be applied?
• Which fields are raw, converted, aggregated or externally enriched?
• What happens when a required value is unavailable?
• When does a previously calculated value become stale?

A useful design exercise is to describe a position from creation through several changes. Follow the actual protocol's rules, including any changes that your selected event set does not directly express. Reading the relevant contract or program is necessary before treating the model as a faithful representation of that protocol.

Keep missing values distinct from zeros. A missing price does not establish a zero-value asset, and an unknown fee does not establish a free transaction. Label incomplete calculations so that downstream consumers can decide whether to exclude or display them.

Build an evidence set from real transactions relevant to the model. Include ordinary activity, transactions involving several related events, failed activity where applicable and changes across protocol versions. Keep the expected interpretation and the reason for it alongside each source reference.

For each record, trace the path from execution context to decoded fields and then to the resulting entity. A parser can produce valid structured output while the business interpretation remains wrong. Review each layer separately to locate the disagreement.

Document what has actually been reconciled. Evidence from one protocol version or a handful of transactions does not establish complete coverage of every event type. Keep unsupported cases explicit and make them available to the people choosing whether the dataset fits their use.

A decoder update can change the meaning of stored data. Treat that as a data release, not only a code deployment. Identify the affected protocols, historical interval and derived tables before deciding whether to rebuild or correct the existing output.

Keep a release record

1. Dependency identity: source package, version and the configuration that produced the output.
2. Schema meaning: entity definitions, field units and supported protocol versions.
3. Change scope: the cases fixed or added and the history that may be affected.
4. Reconciliation: real records reviewed and unresolved differences.
5. Migration: how consumers move to the corrected dataset and how the previous version is retained.

Use a separate destination or versioned dataset when the new output needs comparison before adoption. Keep the consumer-facing contract stable where possible; if the meaning of a metric changes, describe that change directly.

Substreams supports a separation between reusable modules and the custom transformations that consume them. Apply that separation to ownership as well: assign responsibility for dependency updates, protocol coverage and the business model rather than assuming one module maintainer owns the entire application.