Skip to content

docs: pin the RAM byte costs for a transfer's new scope and a market balances row - #16

Merged
robrigo merged 1 commit into
mainfrom
docs/ram-billing-figures
Aug 18, 2026
Merged

docs: pin the RAM byte costs for a transfer's new scope and a market balances row#16
robrigo merged 1 commit into
mainfrom
docs/ram-billing-figures

Conversation

@robrigo

@robrigo robrigo commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

What this change claims, in one sentence:

An AtomicAssets transfer that creates the recipient's first scope bills the sender exactly 112 bytes, and an AtomicMarket balances row costs 121 + 16 x N bytes for N distinct token symbols (the retired wiki's 113 + 16N formula omitted the 8-byte owner field).

Source: AntelopeIO/leap at v5.0.3: libraries/chain/include/eosio/chain/config.hpp:108,140,146, libraries/chain/include/eosio/chain/contract_table_objects.hpp:244-253 (billable sizes of table_id_object and key_value_object, both align to 112), libraries/chain/apply_context.cpp:691,813 (where each is charged); contract row shapes at the existing pins (atomicassets-contract v2.0.0-rc4 src/atomicassets.cpp:1665-1761, atomicmarket-contract v2.0.0-rc2 include/atomicmarket.hpp:519-526); live WAX mainnet wax.greymass.com POST /v1/history/get_transaction: tx 1ec40244151f86b361f9fa18de6ed7bb1413608792141538e0de531a53c55393 (sender ram delta exactly +112) and tx cabbeb2b2760c4d0e3a70363e902362b468775ad98ef970d71e1d2ad1a4788c3 plus two corroborating settlements (balances row exactly +137/-137, matching 121 + 16 for one symbol).

Tier: both, for each figure (pinned-source arithmetic and a live mainnet observation).

Row in validation-log.md updated: yes; both pages move from source-read to both, their rows name the leap baseline and the live reads, the tier distribution moves to 20 source-read, 1 live-chain, 16 both, and AntelopeIO/leap v5.0.3 joins the pinned baselines. Note: this PR and #14/#15 edit disjoint lines and merge in any order, but all three touch files #13 relocates, so merging them before #13 avoids conflicts.

One deviation from the one-claim rule: the two figures share one validation basis (the same leap constants, the same endpoint, the same arithmetic pattern), so they travel together for review.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the documentation corpus to pin and justify two RAM byte-cost figures (AtomicAssets “new scope on transfer” and AtomicMarket balances row sizing), and records the expanded validation basis (adding a pinned AntelopeIO/leap baseline plus live mainnet observations) in the provenance ledger.

Changes:

  • Adds AntelopeIO/leap v5.0.3 as a pinned baseline for chain RAM-billing constants and updates page tiers to both where live observations are now cited.
  • Updates reference/atomicassets/actions.md to state the exact 112-byte sender RAM delta for first-scope transfers, including pinned-source arithmetic and a live WAX mainnet transaction reference.
  • Updates reference/atomicmarket/ram.md to state the 121 + 16×N balances-row byte cost and adds pinned-source + live-transaction citations supporting it.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File Description
validation-log.md Adds leap v5.0.3 baseline, upgrades validation tiers/notes for the affected pages, and updates tier distribution counts.
reference/atomicmarket/ram.md Documents the balances-row byte-cost formula and adds pinned-source + live-chain evidence for the RAM deltas.
reference/atomicassets/actions.md Documents the 112-byte new-scope transfer RAM charge and adds pinned-source + live-chain evidence for the RAM delta.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread reference/atomicmarket/ram.md Outdated
Comment thread validation-log.md Outdated
Comment thread validation-log.md Outdated
@robrigo
robrigo force-pushed the docs/ram-billing-figures branch from 6b4f928 to 43a9bb7 Compare August 18, 2026 20:40
@robrigo
robrigo deployed to wax-testnet August 18, 2026 20:40 — with GitHub Actions Active
@robrigo
robrigo requested a lite review from Copilot August 18, 2026 20:40

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (1)

reference/atomicassets/actions.md:413

  • The 112-byte figure is specifically the billable size of a new table_id_object (table-scope record) per the cited leap constant; saying “new table object” is ambiguous because key_value_object is also a table-related object (and is also 112 bytes). Using the precise object name here will better align the text with the citation and avoid confusion about what is being charged persistently.
Notifies `from` and `to` directly via `require_recipient`, then calls `internal_transfer`, which: requires `to` to exist and differ from `from`; requires every asset to currently belong to `from` and, if templated, to have `transferable = true`; and, if this is the first asset `to` has ever held (an empty scope), makes `from` pay for the new scope's RAM by emplacing and immediately erasing a placeholder row (so the action fails outright if `from` cannot cover that RAM); that charge is exactly 112 bytes, the chain's billable size of a new table object, and it stays with `from` while the scope exists. Sends one `logtransfer` per distinct collection touched by the batch (grouped by `std::map<name, ...>` key order, not caller-supplied order), each of which fans out to that collection's `notify_accounts`.

…balances row

The old wiki carried both figures and was retired with the wiki collapse, but its balances formula was wrong: it omitted the 8-byte owner field, understating every row by 8 bytes. Both figures are now computed from the leap billing constants and confirmed against live mainnet account_ram_deltas, which is what caught the error.
@robrigo
robrigo force-pushed the docs/ram-billing-figures branch from 43a9bb7 to 97de33a Compare August 18, 2026 20:44
@robrigo
robrigo deployed to wax-testnet August 18, 2026 20:44 — with GitHub Actions Active
@robrigo
robrigo merged commit c1ae73a into main Aug 18, 2026
10 checks passed
@robrigo
robrigo deleted the docs/ram-billing-figures branch August 18, 2026 20:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants