docs: add Antelope-to-Wire contract migration guide

[heifner]

Summary

Adds docs/migrating-from-antelope.md — a guide for developers arriving with a working contract from EOS, Telos, WAX, Jungle or another Antelope-family chain. Documentation only; no code changes.

#112 and #113 are merged, and this branch is rebased onto them. The guide describes the current toolchain and keeps the pre-merge behaviour as a caveat for anyone on an older CDT. It now also depends on #115, which fixes the kv::global + _i defect the review turned up — see below.

It is organised as the port actually goes: install and build something first, then the mechanical renames, then storage, then the resource model, then the host-function diff.

What it covers

• Getting started on Wire. Toolchain install (base and -dev packages, plus CMake, a build tool and jq, which the guide's own commands need), the eosio-* → cdt-* / cleos → clio mapping, cdt-init, add_contract, native testing, getting an account, sysio.roa::addpolicy, and deploy. The tarball's bin/ holds the unprefixed clang/lld/llvm-*, so putting it on PATH shadows the distro toolchain — that is called out, along with the cdt-cpp name collision with AntelopeIO CDT 3.0+.
• The rename surface. Full eosio → sysio table, a sed first pass that explicitly covers the eosio_assert / eosio_exit C API a \beosio\b pattern silently skips, and a caution about string literals. The ABI version becomes sysio::abi/1.2. table_id and secondary_indexes are the Wire additions to table_def; index_type, key_names and key_types are original EOSIO fields — what changed is that Wire populates them to describe the key layout.
• Storage. db_*_i64 and db_idx* are gone from CDT and the chain. sysio::multi_index is a compatibility shim — table declarations carry over, but the postfix it++/it-- operators are deleted and need a mechanical sweep. Secondary keys must be std::is_trivially_copyable, not merely serializable. get_table_rows now returns {key, value}. Use _i only above 13 characters, and note that _n is not a universal fallback — its alphabet is .12345a-z, so a name containing _ is a compile error. Reviewing that rule turned up a toolchain defect, now fixed in fix(abigen): keep the annotated table name for a _i-named table #115 rather than documented: abigen named a table by decoding its raw template parameter, which is a hash for _i, so kv::global, multi_index and kv_multi_index emitted a garbage twin beside the annotated name — two mismatched entries under 13 characters, a table_id collision at or above it. kv::table was never affected, because its code path already preferred the annotation. With fix(abigen): keep the annotated table name for a _i-named table #115 merged, _i works at any length on every table kind, and kv-global.md carries a caveat for older toolchains instead of a prohibition.
• Resources. Scoped to what changes in contract code: the emplace(user, …) → emplace(get_self(), …) decision, why sysio.payer at index 0 welds RAM billing to CPU/NET (and the advanced @sysio.code delegation that separates them), and that CPU is billed per top-level action across the whole call tree while NET is fixed by what reaches the wire.
• Host functions. Added (22 × kv_*, get_ram_usage, get_permission_lower_bound, blake2b_256), removed (db_*_i64, the 50 db_idx*, send_deferred/cancel_deferred, get_permission_last_used/get_account_creation_time), and the unchanged surface.
• A porting checklist and a reading list across both repos.

Verification

Every claim was checked against the code rather than assumed, and doing so corrected several of my own errors — including two rounds of review findings that were all accurate.

Notable things the checks changed:

• get_block_num is standard Antelope, so it is not a Wire addition; blake2b_256 is not in Antelope's crypto_ext.h, so it is one.
• The addpolicy example had a C++/ABI camelCase-vs-snake_case note that described a divergence that does not exist — I had read wire-system-contracts' copy of sysio.roa.hpp, abandoned on a 2025 branch, rather than the authoritative wire-sysio/contracts copy.
• The _i short-name table_id mismatch is real and reproduced independently: user_table hashes to 61956 at runtime and 3509 in the ABI, because abigen routes annotated names of ≤13 characters through string_to_name while _i always hashes.
• The NET overhead split is overhead / actions + 1 — integer division then an unconditional +1, which over-bills by up to a byte where the division is exact.

Related

• Depended on fix(kv): reject duplicate primary keys in multi_index::emplace #113 (merged), which restores the duplicate-emplace guard and the receiver guards, and adds a name overload to lower_bound/upper_bound (an earlier revision of fix(kv): reject duplicate primary keys in multi_index::emplace #113 templated them, then replaced that with a converting proxy; both were reverted in favour of the two concrete overloads, so fix(kv): reject duplicate primary keys in multi_index::emplace #113's own history is misleading on this point if read at an intermediate commit). The storage section describes the post-fix(kv): reject duplicate primary keys in multi_index::emplace #113 semantics, so this should merge after it. Without fix(kv): reject duplicate primary keys in multi_index::emplace #113 the same section would have to document an emplace that silently upserts and strands secondary-index entries.
• The ROA overview is referenced through wire-sysio#583, which is still open; the master path does not resolve yet, and the guide says so rather than linking a 404.

Corrections worth calling out

Two of the guide's claims were confidently wrong and are fixed here, because both would have misled the reader in the direction that costs money:

• RAM. Two revisions of this guide got the direction wrong, in opposite directions. It depends on rows-per-scope: the table_id_object is billed per (code, scope, table), so a table with one row per scope — a token balance, a per-user settings row — sheds a whole 108-byte object and comes out 38–41% cheaper, while a dense table with few scopes pays 10–16% more. Across EOS mainnet the net is a 2–6% saving. The guide now gives all four rows from wire-sysio's kv-ram-billing.md and says to size from your own ratio rather than assuming either way.
• clio get table ... -S <gen>. Scoped-table scopes are declared as name, and the chain tries name(scope) before falling back to an integer. 1-5 are valid name characters, so -S 1 is read as the name "1" (576460752303423488) and the query returns no rows — which reads as "your issuer is not a node owner". The command now omits -S.

Not in this PR

The .gitignore hunk was dropped — it was a strict subset of the identical one on #112 and #113 and conflicted with both. It landed on #113, and this branch now takes master's version.

[huangminghuang]

Reviewed the complete diff at 54b55e7. CI is green, but I found several correctness issues in the migration path, including an unrunnable provisioning command and source/API compatibility claims that do not hold. Inline comments contain reproductions and suggested corrections, so I am not approving this revision. As the PR body notes, the cross-repo ROA link also requires Wire-Network/wire-sysio#583 to merge first.

Smaller accuracy corrections: docs/migrating-from-antelope.md:71 has -wasm2wast where the Antelope command is eosio-wasm2wast; line 85 says -bare emits only the header/source skeleton although it also emits the contracts Markdown and README files; line 428 groups sha3 under the assert_ forms although no assert_sha3 is exposed; and the README summary at line 42 should say the contract is billed by default so it does not erase the explicit-payer exception.

[huangminghuang]

The tarball setup contradicts the isolation guarantee above. InstallCDT.cmake installs unprefixed clang, clang++, lld, ld.lld, opt, llc, wasm-ld, and the LLVM tools into this same bin, so putting /opt/wire-cdt/bin first shadows the distro tools. Please scope lines 41–43 to deb/rpm and recommend an absolute cdt-* path, alias, or public-entry-only symlink directory for a coexisting tarball.

[heifner]

Confirmed and fixed in a951e0a. InstallCDT.cmake:59 installs unprefixed clang, clang++, lld, ld.lld, opt, llc, wasm-ld and the llvm-* set into the same bin/, so my advice was actively harmful for the tarball.

The isolation guarantee is now scoped to deb/rpm, where only public entry points are symlinked into /usr/bin. The tarball gets its own callout saying plainly that its bin/ holds everything and that putting it on PATH shadows the distro toolchain, with the three safe options: absolute path, alias, or a private symlink dir holding just the cdt-* names. The AntelopeIO name collision moved into that callout too, since the fix is the same.

[huangminghuang]

This installs only the base component. The native-test workflow linked at line 128 needs libnative*, gen_native_dispatch.py, and share/cdt/native-contract-src, all packaged in wire-cdt-dev; CMake and a build tool are not base-package dependencies either. On a clean machine the later build/native-test steps are therefore unavailable. Please install/document wire-cdt-dev, CMake, and the build tool, or state that those steps assume them.

[heifner]

Confirmed and fixed in a951e0a. libnative*, scripts/gen_native_dispatch.py and share/cdt/native-contract-src are all COMPONENT dev, and neither package depends on CMake or a build tool — so a reader following the page top to bottom would hit "Test without a chain" with nothing to run it.

The install step now takes both packages and adds cmake ninja-build, with a sentence saying which package carries what and why the dev one is needed for the native path further down.

[huangminghuang]

This mandatory command cannot be parsed as written for two independent reasons. The line-ending backslash is inside the still-open single-quoted JSON string, so the shell passes a literal backslash/newline; and the ABI fields are snake_case (net_weight, cpu_weight, ram_weight, time_block, network_gen), not camelCase. Current clio convert pack_action_data fails with Missing field 'net_weight'. Please keep the JSON on one quoted line (or use a safe file/input form) and use the ABI field names.

[heifner]

Confirmed and fixed in a951e0a — and the camelCase was my own regression. The original draft had snake_case; I "corrected" it against sysio.roa.hpp, whose parameters are netWeight etc., without checking that contracts/sysio.roa/sysio.roa.abi declares net_weight / cpu_weight / ram_weight / time_block / network_gen. Good catch.

The command is now a single line with the ABI names, plus a note on both traps: the ABI spelling is not the C++ parameter spelling, and a wrapping \ lands inside the single quotes rather than continuing the line.

[huangminghuang]

Please scope this to ordinary/default contract-paid calls. A provisioned caller or relayer can opt in as the explicit CPU/NET payer using an index-0 sysio.payer authorization plus the matching real authorization, so it is not true that nobody can call the contract or that every call fails when the contract itself has zero CPU/NET.

[heifner]

Agreed, fixed in a951e0a. It also contradicted the ROA page I link to, which says an unprovisioned contract is "inert for ordinary users, not universally inert".

Now scoped: an ordinary call fails, and because billing keys on the payer alone, a caller naming itself with sysio.payer pays for the action and never consults the contract's zero limits — so a provisioned caller or relayer can still drive it.

[huangminghuang]

The word boundary prevents exactly the C API renames listed above: _ is a word character, so \beosio\b does not match the eosio prefix in eosio_assert or eosio_exit. Those identifiers remain unchanged. Please add explicit substitutions (or a token-aware rename) so the advertised first pass covers them.

[heifner]

Confirmed and fixed in a951e0a. _ is a word character, so \beosio\b has no boundary to match in eosio_assert — the recipe skipped precisely the C API entries listed in the table right above it.

Verified both directions on a fixture containing eosio_assert, eosio_assert_message, eosio_exit, eosio::name, EOSIO_DISPATCH and EOSLIB_SERIALIZE: the old recipe leaves the three C API lines untouched, the new one converts all six. The added expression names them explicitly, and the text says why it is not redundant.

[huangminghuang]

multi_index is not fully source-compatible: Wire explicitly deletes postfix operator++(int) and operator--(int) on both primary and secondary iterators, while Antelope provides them. Common loops such as for (...; it != table.end(); it++) fail to compile (this repo's existing examples use that form). Please document the required it++ → ++it / it-- → --it migration or restore those operators, and soften “drop-in” / “usually does not change at all.”

[heifner]

Confirmed and fixed in a951e0a. operator++(int) and operator--(int) are = delete at kv_multi_index.hpp:422-423 (primary) and 807-808 (secondary).

"Drop-in" is now "near-drop-in", the TL;DR row says to expect a mechanical it++ → ++it sweep, and there is a short subsection showing the failing loop, the rewrite, and why a postfix increment cannot work when the iterator owns a host-side handle. Added to the porting checklist as its own step.

Worth flagging separately: examples/multi_index_example and examples/multi_index_large use itr++ in five places, so those examples cannot compile as written — they are evidently not built by CI. I have left them alone as out of scope for a docs PR, but they look like a real breakage.

[huangminghuang]

The generic encoder does not make every serializable type usable here. secondary_index_view has a std::is_trivially_copyable static assertion, so serializer-supported types such as std::string and std::vector are rejected. Please state the actual constraint rather than “anything else with a CDT serializer.”

[heifner]

Confirmed and fixed in a951e0a. The static_assert(std::is_trivially_copyable<secondary_key_type>::value, ...) at kv_multi_index.hpp:769 is the real constraint, and "anything else with a CDT serializer" claimed the opposite of what it enforces.

The text now states the actual rule and notes that std::string / std::vector keys are rejected at compile time despite being serializable, with the practical workaround — hash to a checksum256, or truncate to uint64_t and disambiguate against the primary row. Also added as a checklist step.

[huangminghuang]

This recipe is unsafe for annotated _i table names of 13 characters or fewer. Runtime _i always DJB2-hashes the literal, but abigen::add_table sends short annotated names through legacy string_to_name; the runtime and ABI table_id then differ (for example, user_table is 61956 at runtime versus 3509 in the ABI). RPC metadata can point at the wrong table. Please fix ABI generation first or document/restrict the safe naming case.

[heifner]

Confirmed and fixed in a951e0a — and I reproduced your figures independently before changing anything. abigen.hpp:297-306 branches on t.name.size() <= 13, taking string_to_name for short names, while _i in hash_id.hpp DJB2-hashes unconditionally:

name	runtime (_i)	ABI
user_table (10)	61956	3509
accounts (8)	64120	25660
user_balance_history (20)	26461	26461

So it is every short annotated name, not an edge case.

I documented the restriction rather than attempting the fix here, since changing add_table moves the table_id of any contract already using that path and is a breaking ABI change that wants its own PR and a pinned toolchain test. The guide now says to use _i only above 13 characters — where both sides hash and agree, which is the case _i exists for — and _n below, where both use string_to_name and likewise agree. The table above is in the page so the failure mode is recognisable.

Happy to open the codegen fix as a follow-up if you would rather have it than the restriction.

[huangminghuang]

Please qualify this as objective billing. Subjective billing is enabled by default for API/P2P traffic, and the pre-execution check applies the subjective failure/CPU budget to non-payer first authorizers. Thus the signer has no objective CPU/NET charge, but can still be limit-checked and throttled after failed attempts.

[heifner]

Confirmed and fixed in a951e0a. verify_init_subjective_billing takes set_difference(first_authorizers, payers) and, for each authorizer that is not a payer, throws tx_cpu_usage_exceeded / greylist_cpu_usage_exceeded when the subjective budget is gone — so the signer is very much limit-checked, just not by consensus.

The claim is now scoped to objective billing, with a following paragraph on subjective billing metering the first authorizer, that it is node-local rather than consensus, and that a signer failing transactions in a loop can be throttled.

[huangminghuang]

NET is not based on the whole transaction's serialized bytes. packed_transaction::get_action_billable_size() charges a fixed per-action overhead plus only that top-level action's serialized billable size (and its matching context-free data when applicable); it excludes headers, signatures, and other actions. Please describe that per-action formula, since it changes the provisioning/sizing guidance.

[heifner]

Half agreed — the sentence was wrong and is fixed in a951e0a, but I do not think the replacement formula is right, so flagging rather than adopting it silently.

get_action_billable_size is indeed per-action, and my "on the transaction's serialized bytes" was wrong. But the overhead it adds is not a fixed constant excluding headers and signatures — it is billable_net_per_action_overhead, computed in packed_transaction::init:

int64_t size = config::fixed_net_overhead_of_packed_trx;      // 16
size += fc::raw::pack_size(signatures);
size += fc::raw::pack_size(unpacked_trx.transaction_extensions);
size += fc::raw::pack_size(static_cast<const transaction_header&>(unpacked_trx));
billable_net_per_action_overhead = (size / unpacked_trx.total_actions()) + 1;

Signatures, extensions and the header are all in there; they are apportioned across the actions rather than excluded. Only other actions' payloads are excluded, which is the part your comment gets right and my sentence got wrong.

That distinction is exactly what changes the sizing guidance, so the page now gives the full formula:

action NET = that action's own serialized billable size
           + (16 + signatures + extensions + header) / number of actions, rounded up
           + its matching context_free_data, for a context-free action

with the two consequences that follow: signatures cost NET, so co-signing is dearer; and batching amortizes the overhead. This also matches wire-sysio's docs/roa-overview.md, which the page links to. If I have misread init(), say so and I will correct it again.

[huangminghuang]

Re-reviewed the complete PR and the follow-up delta at a951e0a. The follow-up resolves the original 11 inline findings and all current-head CI checks are green, but I found additional compatibility and resource-model issues, including a state-integrity break in the current multi_index::emplace shim. Inline comments have the implementation evidence and requested wording, so I am not approving this revision.

The PR description also needs the required full-diff refresh: it still calls multi_index a drop-in shim requiring no source changes, contrary to the follow-up commit and the current guide. Smaller corrections remain at docs/migrating-from-antelope.md:89 (eosio-wasm2wast, not -wasm2wast), line 103 (cdt-init -bare also emits the contracts Markdown and README), and line 167 (the C++ addpolicy parameters are snake_case too, not camelCase). Keep the documented merge ordering behind Wire-Network/wire-sysio#583; that PR is still open and the master-branch ROA link still does not resolve.

Correction to my prior review body: sysio::assert_sha3 does exist as a library wrapper in crypto_ext.hpp, so that earlier minor note was wrong and is withdrawn.

[huangminghuang]

These clean-machine prerequisites are not sufficient for the commands the guide gives. This installs Ninja, but line 99 invokes the default generator and make; line 253 newly requires jq, which is not installed here. Please either install build-essential jq, or select Ninja consistently (-G Ninja / cmake --build) and add jq.

[heifner]

Fixed in 2653497. The prereq line installed Ninja while the guide then ran the default generator and make, and never installed jq at all. Now sudo apt install cmake build-essential jq, with a sentence saying which command each is for — keeping make, since that is what the cdt-init project generates.

[huangminghuang]

The later paragraph now documents the explicit-payer exception correctly, but this sentence (and the introduction at line 5) still says nobody can call an unprovisioned contract. Please say before an ordinary/default contract-paid call. Also, the explicit payer bypasses only the contract's zero CPU/NET; any new RAM the contract bills to itself still needs RAM headroom.

[heifner]

Fixed in 2653497, at both places — the introduction now says the contract is what has to be provisioned "before ordinary calls will go through", and the deploy section says "ordinary contract-paid call".

The RAM point is a good catch and I have added it explicitly: the sysio.payer route bypasses the contract's zero CPU/NET only, so RAM the contract bills to itself still comes out of its own quota — an unprovisioned contract can be driven no further than its first write to its own tables.

[huangminghuang]

Hard-coding network_gen:0 is not valid for a generic shared network. addpolicy opens nodeowners in the supplied generation and requires the issuer there; after a generation rollover, a valid issuer registered elsewhere fails or this draws from an old generation's allocation. Use a placeholder and explain how to query/select the issuer's intended generation.

[heifner]

Fixed in 2653497. addpolicy opens nodeowners scoped to the generation passed and requires the issuer there, so a literal 0 is wrong on any network that has rolled over.

It is now <gen>, with a paragraph explaining it is the generation the issuer is registered in and two commands to determine it — read network_gen from the roastate singleton, then confirm the issuer appears in that generation's nodeowners.

[huangminghuang]

near-drop-in is still unsafe as written. Wire emplace calls kv_set without kv_contains; when the primary key already exists, the chain takes its update branch, whereas legacy db_store_i64/emplace rejects the duplicate. If the secondary key changed, store_secondaries then adds the new mapping without removing the old one, leaving stale index state. Separately, primary lower_bound/upper_bound accept only uint64_t, so code using a name primary key no longer compiles while upstream accepts its templated PK. Please fix the shim or explicitly document both safeguards/conversions, and remove the one source change framing.

[heifner]

Both confirmed, and I fixed the shim rather than documenting around it — #113.

The orphan reproduced exactly as you described, and I demonstrated it against the real runtime before changing anything: emplace pk=1 sec="aaa", emplace pk=1 sec="bbb", then look up "aaa".

before:  ORPHAN: stale secondary A still resolves after duplicate emplace
after:   object with the same primary key already exists

emplace now checks kv_contains first, the way kv::table::emplace already did — the compat shim was the one missing what the perf-first wrapper pays for. lower_bound/upper_bound are templated on the primary key type like upstream's to_raw_key; making that work surfaced three further sites passing primary_key() straight into pk_to_bytes, which now use the same to_pk_uint64 conversion.

Here in 2653497: the "one source change" framing is gone, multi_index is a compatibility shim rather than near-drop-in, and the section states that duplicate-emplace and the bounds signatures match upstream. This PR now depends on #113.

[huangminghuang]

The guide's own user_table example cannot follow this advice: _n rejects _ (its alphabet is .12345a-z, with an additional 13th-character restriction), so it is a compile-time error. Only short identifiers that are valid Antelope names can switch to _n; other short _i identifiers must be renamed/lengthened until abigen is fixed.

[heifner]

Confirmed and fixed in 2653497 — the fallback I offered was impossible for the very example above it. basic_name's alphabet is .12345a-z and symbol() calls sysio::check on anything outside it, which in a constexpr _n literal is a compile error, so "user_table"_n never builds.

The callout now says _n is the fix only for short names that are already valid Antelope names, and that a short identifier containing _, a digit outside 1-5, or an uppercase letter has to be renamed or lengthened past 13 characters until abigen is fixed.

[huangminghuang]

This is presented as an exact formula, but consensus computes integer division followed unconditionally by +1: floor(overhead / action_count) + 1. That differs from mathematical ceiling whenever the overhead divides evenly (including every one-action transaction), understating each action by one byte. Please show the actual integer formula.

[heifner]

Agreed that "rounded up" was wrong, and fixed in 2653497 — but I read the direction the other way, so flagging rather than adopting it silently.

billable_net_per_action_overhead = (size / unpacked_trx.total_actions()) + 1 is floor-then-+1. When the division is exact, floor(x/n) + 1 is one more than ceil(x/n), so each action is billed a byte over, not under. transaction.cpp:380 agrees:

// +1 rounds up so per-action shares sum to at least total overhead; may over-bill
// by up to total_actions() bytes per trx (negligible).

The guide now shows the arithmetic in two steps rather than calling it a ceiling, and says it over-bills by up to a byte per action where the division is exact. If I have the sign backwards I will correct it again — but the code comment reads the same way I do.

[huangminghuang]

Only CPU has the whole-call-tree property. As line 453 correctly says, inline actions and notifications add zero NET; NET consists of the input action's bytes, its apportioned transaction overhead, and matching context-free data. Please split this conclusion so it does not say a contract's NET provisioning covers everything the action causes.

[heifner]

Confirmed and fixed in 2653497. The conclusion had generalised a CPU property to NET, contradicting the sentence four lines above it.

It now says explicitly that only CPU has to cover everything the actions cause, since the whole tree is timed against the top-level payer, while NET is fixed by what reaches the wire — the input action's bytes, its share of the overhead, and its context-free data — and no inline action or notification adds to it however deep the tree goes.

[huangminghuang]

unchanged source contradicts the mandatory iterator rewrite above, the name-primary bounds mismatch, and the fact that direct db_* callers necessarily must be rewritten. Please point readers to the compatibility adjustments instead.

[heifner]

Fixed in 2653497. The checklist entry now says direct db_*_i64 / db_idx* callers must be rewritten, and that multi_index users need only the iterator sweep in the preceding step. The "unchanged source" phrasing in the removed-intrinsics table is replaced with a pointer to the compatibility adjustments in Step 2.

[huangminghuang]

This new cross-link still says drop-in, contradicting the migration guide's postfix caveat and the additional verified emplace/name-primary differences. Please call it a compatibility shim or near-drop-in and link the required adjustments rather than promising unchanged behavior.

[heifner]

Fixed in 2653497. That cross-link now calls multi_index a compatibility shim rather than a drop-in, names the required it++ → ++it sweep as the reason, and tells the reader to make those adjustments before treating the KV migration as an optional second step.

[huangminghuang]

The current guide now documents sysio.payer, so this summary should say the contract is billed by default. RAM is also selected by the contract's payer argument rather than categorically never landing on the signer.

[heifner]

Fixed in 2653497. The README summary now says the contract is billed for CPU and NET by default rather than the signer, and that RAM follows whichever account the contract names as payer instead of categorically never reaching the signer.

[heifner]

Also addressed the four items from the review body, in 2653497:

• :89 — eosio-wasm2wast, not the -wasm2wast shorthand.
• :103 — cdt-init -bare emits four files, not two. write_ricardian() runs unconditionally (cdt-init.cpp:206), so a bare project also gets <name>.contracts.md and README.txt.
• :167 — you were right, and this one was my own regression. I had "corrected" the field names to camelCase against wire-system-contracts' copy of sysio.roa.hpp, which sits on a feature branch last touched 2025-09-18; the authoritative wire-sysio/contracts/sysio.roa/sysio.roa.hpp is snake_case on both the C++ and ABI sides. There is no divergence to describe, so the note is deleted rather than reworded.
• Merge ordering — the ROA overview is now referenced through wire-sysio#583 rather than a master URL that 404s, and the guide says so in both places it appears.

PR description refreshed for the full diff, as required. It no longer calls multi_index a drop-in needing no source changes.

This PR now depends on #113, which fixes the two code defects from your :274 comment. The orphan reproduced exactly as you described — I demonstrated it against the real runtime before touching the shim, and the storage section here describes the post-#113 semantics rather than documenting a hazard we are removing.

Thanks for both rounds — the stale-repo one in particular caught a mistake I had introduced while fixing an earlier finding.

[heifner]

Reviewed against merged master (532f3841b, which now carries both #112 and #113) and pushed 7ed8f269c. This branch was 57 commits behind, so it described both as forthcoming.

One claim had gone false

The Unchanged host functions list promised "every privileged.h setter". #112 removed set_kv_parameters_packed, which was one of them. Fixed, and the two things #112 deleted now have rows in Removed on Wire — with the diagnostic each actually produces, since they differ and the difference is what a porter sees:

#include <sysio/security_group.h>   → fatal error: 'sysio/security_group.h' file not found
set_kv_parameters_packed(...)       → error: use of undeclared identifier

The header is gone outright in the first case; in the second <sysio/privileged.h> is still there and set_privileged from it still compiles — I checked both.

Tense, where it changed the advice

The ABI section told readers not to reach for cdt-abidiff, on the strength of limitations #112 fixed. That advice is now backwards, so it is inverted: the section lists what the tool compares today — version as the full string, structs, types, actions, tables with the full metadata and secondary indices, ricardian_clauses, enums, protobuf_types, variants, action_results, error_messages — and keeps the old-toolchain caveat plus the jq fallback for anyone on an older CDT.

The legacy-database and multi_index sections, and the three matching blocks in docs/kv-multi-index.md, now describe the current toolchain with the pre-merge behaviour as the caveat rather than the other way round.

One gap in both docs

The #113 receiver guard reaches sysio::singleton and neither doc said so. get_or_create, set and remove all mutate through the kv_multi_index it holds, so a singleton handle on another account's code is read-only exactly like a table handle. Added to both. While there: docs/kv-multi-index.md said singleton "is backed by" kv_multi_index, which reads as inheritance — it holds one as a member.

Verified, not reworded

Rebuilt CDT at merged master and compiled the claims:

Claim	Result
it++ is deleted	rejected — overload resolution selected deleted operator '++', the exact text the guide quotes
hand-declared db_store_i64 is now a link error	wasm-ld: undefined symbol: db_store_i64
the static_cast<...>(&table::lower_bound) escape hatch	compiles
lower_bound takes name, uint64_t and {42}	all compile
22 kv_* intrinsics, none in the allow-list	22 / 0 ✓
imports/cdt.imports.in after the trim	87 entries, 0 db_* ✓
default ABI version 1.2, 1.3 with protobuf	matches default_minor / protobuf_minor ✓

The RAM tables, _i / hash_id and get_table_rows sections are untouched by either PR and I left them alone.

Still worth doing before merge: this branch is 57 commits behind master. It merges clean, but the diff is easier to trust rebased.

[huangminghuang]

Reviewed current head 7ed8f269. CI is green, but I found remaining accuracy and portability issues, so I cannot approve this revision yet. The inline comments below are all against the current head.

Please also refresh the PR description after the follow-up commits: #113 is now merged, key_names/key_types are upstream ABI fields rather than Wire additions, and the _i/example impact statements no longer match this revision.

[huangminghuang]

[P2] Make the examples follow this warning. The page still says both literal forms work, shows the >13-character "app_configuration"_i form that this block says fails to link, and its complete example uses short "app_config"_i with a table annotation, which this block says emits mismatched ABI metadata and breaks readable get_table_rows. Please make the runnable examples use _n (and drop the annotation/hash include if no longer needed), reserving _i for a labeled limitation. Also qualify the name rule: position 13 only accepts .12345a-j, not the full alphabet.

[heifner]

You were right that the examples contradicted the block — but chasing it turned up that the block itself was describing a toolchain bug, not a property of _i. Opened #115 to fix it rather than document it.

abigen's add_table() named each entry by decoding the raw template parameter, which is a DJB2 hash for _i, not a name encoding — so it emitted a garbage twin (idrzzw4ktxljf, 5p.tmiidfxofh) beside the annotated name. Under 13 characters that is the two mismatched entries this block describes; at or above it the two hash to one table_id and the link fails. add_kv_table() — the kv::table path — already preferred the [[sysio::table]] attribute, which is exactly why kv::table + long _i has always worked and is tested. multi_index and kv_multi_index were affected too.

So this page no longer tells readers _i is unsuitable. Changes in 64b40a9eb:

• the block is scoped to a pre-fix(abigen): keep the annotated table name for a _i-named table #115 toolchain and says what it was, rather than presenting it as how _i behaves;
• the alphabet rule is qualified as you asked — _n covers up to 13 characters of .12345a-z, with position 13 restricted to .12345a-j, since it is encoded in 4 bits rather than 5. Confirmed in name.hpp: value & 0x0Full and >> (i == 12 ? 60 : 59);
• the examples use _n where the name fits one, and the hash_id.hpp include is dropped from the complete example, which no longer needs it.

One more thing fell out while making that example runnable. It emitted no ABI table entry at all — and neither does the shipped examples/kv_global_example. A namespace-scope struct carrying only [[sysio::table]] is not reachable from the contract, so abigen skips it; it needs to be declared inside the contract class, or to carry sysio::contract("...") beside the table attribute. The example is now in-class and emits ('appconfig', 46121), and the "ABI requirement" note states the reachability rule instead of implying the annotation alone is enough. examples/kv_global_example has the same defect and is not fixed here — it is out of scope for a docs PR, and I would rather raise it separately than smuggle it in.

[huangminghuang]

[P2] Reverse iteration escapes this compiler check. rbegin()/rend() expose std::reverse_iterator, whose postfix operator still compiles and copies the underlying KV handle. The main guide at lines 349-352 already explains this. Mirror that warning here and require a manual sweep of reverse loops instead of promising that the compiler finds every use.

[heifner]

Confirmed, and the contradiction was internal — the main guide already says "The compiler does not find every one." while this page promised the opposite. Fixed: the bullet now says the compiler finds every direct use but not the reverse ones, spells out that rbegin()/rend() return a std::reverse_iterator whose postfix operators belong to the adaptor and are not deleted, gives the loop that compiles clean while doing the handle-duplicating copy, and requires a manual sweep.

[huangminghuang]

[P2] Document the actual overload source break. An upstream call such as t.template lower_bound<uint64_t>(k) (or upper_bound) is valid because those APIs are member templates, but Wire's concrete overloads reject that syntax; a wrapper convertible to both name and uint64_t can also become ambiguous. Current kv_multi_index.hpp comments document both cases. Add them here and to the porting checklist; the bare member-address example is not a Wire-only incompatibility.

[heifner]

Confirmed by compiling it:

error: 'lower_bound' following the 'template' keyword does not refer to a template

That is a much better example than the bare member address, and you are right that the member-address case is not Wire-only — the guide even says upstream cannot deduce PK there either. Restructured into the two real breaks: the explicit template argument, and the dual-convertible wrapper ambiguity (where against a single uint64_t parameter it used to pick the uint64_t conversion). The member-address case is demoted to a parenthesis noting it fails on both sides, with the static_cast escape hatch kept.

[huangminghuang]

[P2] Upstream does not accept arbitrary serializable secondary keys. Its index backend supports only uint64_t, uint128_t, double, long double, and checksum256/fixed_bytes<32>; those types are trivially copyable. The supported fixed type set is therefore a shared restriction. Wire differs mainly in when and how the static_assert diagnoses it, so please remove this false contrast.

[heifner]

You are right, and the guide contains its own disproof: the "Removed on Wire" table lists the upstream secondary-index backend as exactly db_idx64_*, db_idx128_*, db_idx256_*, db_idx_double_*, db_idx_long_double_* — five families, the same fixed set, all trivially copyable. Removed the false contrast. The bullet now says the supported set is upstream's and that what differs is the diagnosis: Wire's static_assert sits in secondary_index_view, so it fires at the first get_index<...>() rather than at the declaration.

[huangminghuang]

[P2] This is not source-compatible. The replacement changes the template from <Name, T, ...> to <Name, K, V, ...>, splits the row/key representation, changes primary-key access and mutator signatures, and moves the payer. This file's own migration example shows the required rewrite. Call it a migration target or API-similar alternative rather than source-compatible.

[heifner]

Confirmed — and as you say, the page's own worked conversion demonstrates it. Reworded to "a migration target for multi_index, not a drop-in", listing what the port actually costs: <Name, T, ...> → <Name, K, V, ...>, the row splitting into separate key and value types, primary-key access changing with it, and the payer moving to the first parameter of every mutator. The performance points that followed are now framed as what the rewrite buys.

[huangminghuang]

[P2] Qualify the 2-6% result. The linked analysis calls this an estimate and obtains 2-6% only when excluding xsat. Including xsat, secondary storage is approximately break-even for kv::table and 5% higher for multi_index. Please say estimated 2-6% excluding xsat, or show both population results.

[heifner]

Confirmed against the source: kv-ram-billing.md:130 says "On the EOS mainnet (excluding xsat), KV saves 2-6%", and §§ at lines 92/100 give both populations. Fixed to say estimated, excluding xsat, and to give the other side too — including it, secondary storage alone is break-even for kv::table and ~5% higher for multi_index, with the reason (legacy index256_object stores its 32-byte key inline; KV always pays a shared_blob offset pointer). 345M of the 355.6M idx256 entries come from xsat, which is why the population choice moves the number.

[huangminghuang]

[P2] assert_sha3 exists. Current crypto_ext.hpp defines sysio::assert_sha3, and the unit tests exercise it. The same header also exposes keccak and assert_keccak, which are omitted from this claimed full cryptographic surface. Preserve assert_sha3 and include the Keccak pair (or narrow the wording if this is not intended to be exhaustive).

[heifner]

Confirmed — all four exist in crypto_ext.hpp and compile. Fixed in 64b40a9eb: the line now reads sha1/sha256/sha512/ripemd160 with their assert_ forms, then sha3 and keccak with theirs (assert_sha3, assert_keccak). The "no assert_ form, here or upstream" claim was simply wrong.

[huangminghuang]

[P2] Audit singleton payer calls too. Existing ports commonly call singleton::set(value, user) or get_or_create(user, ...); kv_singleton forwards that payer into kv_multi_index::emplace/modify, so these calls hit the same missing-sysio.payer runtime rejection. Generalize this to every storage mutator accepting a payer and name the singleton calls explicitly.

[heifner]

Confirmed — kv_singleton::set and get_or_create both forward their payer into _t.emplace / _t.modify, so they hit the same rejection. Checklist item 7 is generalized to "every storage mutator that names a user as payer" and names the singleton calls explicitly alongside emplace/modify.

[huangminghuang]

[P2] Current cdt-abidiff does compare this metadata. #112 is merged: diff_tables() now checks table_id, key_names, key_types, and secondary_indexes as well as type/index_type. Recommend current cdt-abidiff, keeping the raw JSON diff only as a fallback for pre-#112 installations. Also include abi_extensions if lines 299-302 are meant to enumerate every compared section.

[heifner]

Both correct, and both were mine from the previous commit — I fixed the ABI section and left its duplicate in the checklist 400 lines later, which is the exact failure mode I keep flagging in these reviews.

Checklist item 9 now recommends cdt-abidiff and keeps the raw JSON diff as the pre-#112 fallback. And abi_extensions is added to the enumerated list — I had derived that list by grepping diff_*() calls, which misses it because it goes through diff_opaque_section("abi_extensions") at line 660 rather than a diff_abi_extensions().

[huangminghuang]

[P3] Most of these tools have no sysio-* original. The install rules retain sysio-* aliases only for pp, wast2wasm, and wasm2wast; there is no corresponding sysio-cc, sysio-cpp, sysio-ld, sysio-abidiff, sysio-init, sysio-codegen, or protobuf command. Name the three aliases explicitly so readers do not look for commands that are not installed.

[heifner]

Confirmed — the installed bin/ has exactly three: sysio-pp, sysio-wasm2wast, sysio-wast2wasm. The text implied all eleven entry points had sysio-* originals. Now names the three and says explicitly there is no sysio-cc, sysio-cpp, sysio-ld, sysio-abidiff, sysio-init, sysio-codegen or sysio-protoc, so readers reach for the cdt- name.