A token ledger becomes unreliable when it treats a symbol as an identity or a rounded display value as the original amount. These shortcuts are convenient until two assets share a name, a decimal setting changes an import, or a wallet history disagrees with a balance query.
The solution begins with a few precise distinctions: the asset, the address holding it, the unit in which its amount is stored, and the evidence describing a change. The token altcoin ledger guide introduces these building blocks. This article shows how to turn them into records that survive later review.
Build an asset register before importing movements
For an EVM token, use the network and contract address together as the primary asset key. Preserve a human-readable name and symbol in separate fields. A symbol can make a report easier to scan, but it cannot establish that two records describe the same asset.
The contract address identifies the token contract in this context; it is not the recipient address for every transfer. MetaMask's token contract documentation makes this distinction. In your register, label token contract, sender, and recipient as separate fields so importing software does not confuse their roles.
Record where the asset identity came from and when it was checked. An issuer's published contract listing, a protocol deployment record, and an explorer label offer different kinds of evidence. Preserve the source record and any uncertainty instead of silently turning an unverified display label into a verified identity.
Use a distinct identifier scheme for assets outside the EVM. The goal is consistent uniqueness within your ledger, not forcing every network into an Ethereum-shaped address model.
Preserve raw quantities and decimal scaling
The ERC-20 token standard defines a token interface with balance and transfer methods. Its optional decimal metadata tells an interface how to scale an integer amount for display. Names, symbols, and decimals should not be assumed to exist in every implementation.
For a hypothetical token with six decimals, a raw amount of 1,250,000 represents 1.25 displayed units. Keep both the raw integer and the decimal setting that produced the display value. The calculation is raw amount divided by ten raised to the number of decimals.
This structure exposes errors that a formatted spreadsheet can hide. Reading that same integer with eighteen decimals produces a very different displayed quantity. The raw event has not changed; the interpretation has. Correct the interpretation while preserving the source.
Store large raw integers as exact integers or decimal strings. Avoid formats that round them during import. For presentation, you may display fewer decimal places, but calculations and reconciliation should use the underlying precision. A rounded report should be reproducible from the retained values.
Separate event history from balance observations
A movement journal describes events. A balance snapshot describes state at a specified observation point. Keep both, because each answers a question the other cannot answer alone.
For an EVM token event, retain the network, contract, transaction hash, log index, sender, recipient, and raw amount. A transaction can contain multiple relevant logs, so the transaction hash alone may not uniquely identify one movement. Ethereum's JSON-RPC documentation distinguishes transaction receipts and their logs, providing the underlying structure for this evidence.
A balance observation needs the wallet address, asset key, returned raw quantity, and block reference. Also record the retrieval time and source. When comparing two results, check that they refer to the same block rather than assuming the latest value was identical during both requests.
Reconstruct the expected closing balance from the opening observation and recognized changes. If it differs from a direct balance observation, retain the exception. Do not insert an unexplained transfer just to force agreement.
Permissions do not belong in the movement total
An allowance describes authority for a spender. A token balance describes units associated with an address. A transfer describes an actual change between addresses. Ethereum's ERC-20 documentation presents these as separate functions and events, and your record structure should preserve that separation.
Keep approval history beside the journal using a reference to the owner, spender, asset, and transaction. Do not subtract an approved amount from the owner's token quantity. The wallet permissions guide explains how to review authority that may persist after an interaction ends.
Be precise about what ownership means
For a fungible token, a balance query reports the amount assigned to an address under the contract's rules. Your own address register can connect that address to an internal account or wallet label. Keep that connection as a documented assertion with its own evidence.
For an ERC-721 asset, the token identifier matters alongside the network and contract. The standard's owner query concerns a particular token identifier. Recording only the collection name would leave the individual asset unspecified.
Neither kind of ledger entry should be stretched into an unsupported statement about the identity of a person, possession of signing keys, or rights to an external object. A token record and a separate contractual claim may be related, but the relationship needs evidence beyond a display name.
Handle contract changes and unusual behavior explicitly
If a project migrates to another contract, create a new asset record and document the relationship. Retain the old record and the events supporting any conversion. Reusing the old identifier for a new contract makes historical transactions appear to involve an asset that did not produce them.
Similarly, record any verified implementation change or special token behavior that affects interpretation. OpenZeppelin's token documentation describes extensions such as pausing and wrapping, illustrating why a shared interface does not imply identical behavior.
When a balance changes without a movement your importer recognizes, investigate the token's actual accounting model. The source may be incomplete, the interpretation may be wrong, or the contract may require a specialized adapter. Mark the unknown clearly until evidence distinguishes those possibilities.
A general-purpose ledger does not need to decode every token immediately. It does need to make unsupported assumptions visible.
A practical import example
Suppose an export contains three rows labeled SAMPLE. Two belong to contract A on one network, and the third belongs to contract B on another network. The shared symbol is merely an example; these are hypothetical assets.
Create two asset keys, then import the rows using their actual identifiers. If contract A uses six decimals, retain that setting with its raw quantities. Verify contract B independently rather than copying A's metadata across the symbol match.
Next, compare the event identifiers. If the two A rows share a transaction hash but have different log indexes, inspect them as potentially separate movements. If they repeat the same event from two exports, preserve both source references while avoiding a duplicate journal entry.
Finally, compare each reconstructed balance with a snapshot for its own asset and network. An error in A should not be canceled by a similar amount in B. Only after these checks should a summary group the verified positions for presentation.
Keep these matching rules in the data dictionary. Consistent rules prevent the next import from recreating a previously resolved symbol or decimal error, while leaving the original evidence available for review.
Questions about token ledger design
What if decimals are missing?
Preserve the raw amount and flag the display quantity as unresolved. Seek reliable contract or issuer evidence. Guessing a common decimal setting converts missing metadata into a potentially large quantity error.
Can I identify a token by its logo?
A logo is presentation metadata. Use the network and exact asset identifier for matching, then attach any verified display information. Similar artwork does not establish a shared contract or issuer.
Does a successful transaction always mean the expected tokens arrived?
Verify the relevant movement and recipient balance evidence. A transaction status describes execution at its own level; your record still needs to identify which operation occurred and what quantities actually changed.
Keep the source more precise than the summary
The token ledger framework works best when exact identifiers and quantities remain available beneath readable labels. Preserve raw records, annotate interpretations, and let unresolved differences remain visible. The reconciliation process can then explain changes without confusing asset identity, spending permission, custody, or a separate ownership claim.
