docs: hold the SDK pages and the market guides to the shipped 2.1.1 and 2.4.1 releases - #9
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Updates the repository’s documentation to reflect the shipped @atomichub/atomicassets 2.1.0 and @atomichub/atomicmarket 2.3.0 SDK surfaces, and corrects previously incorrect statements about API behavior (notably sales route exposure and royalty 416 semantics). It also aligns the practical guides with the SDK “composer” flows and adds a learning-log mechanism for claims that can’t yet be validated.
Changes:
- Refresh SDK reference pages to the shipped releases, expanding them into route/method and action/composer surface tables with updated behavioral notes.
- Update API reference to document both
/atomicmarket/v1/salesand/atomicmarket/v2/sales, and clarify royalty routes returning HTTP 416 when config is missing. - Update market guides to include SDK composer-based worked flows; add a learning log entry for an explicitly unvalidated
/v2/salesclaim; update the validation ledger baselines accordingly.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
validation-log.md |
Updates SDK baselines to shipped tags and refreshes page verification notes. |
reference/sdk/atomicmarket.md |
Rewrites AtomicMarket SDK page for 2.3.0: full read surface, action builders, composers, and delphi settlement math. |
reference/sdk/atomicassets.md |
Rewrites AtomicAssets SDK page for 2.1.0: getter surface tables, lazy action getter behavior, encoding rules, numeric guards, and deprecations. |
reference/api.md |
Documents dual sales list routes and royalty 416 behavior on the hosted deployment. |
learning/INSTRUCTIONS.md |
Adjusts learning-log intent/format to hold “not yet validated” claims discovered during documentation work. |
learning/api.md |
Adds an explicitly unvalidated claim about /v2/sales excluding WAITING sales, with a validation plan. |
guides/sales.md |
Adds composer-based listing/purchase examples and clarifies settlement_quantity rules and delphi settlement derivation. |
guides/querying-the-api.md |
Adds mainnet vs testnet host table and emphasizes percent-encoding of caller-supplied URL parts. |
guides/buyoffers.md |
Adds composer-based accept/fulfill flow examples and bundle opt-out notes. |
guides/auctions.md |
Adds composer-based announce+escrow example and notes the duration serialization guard. |
guides/asset-lifecycle.md |
Adds a worked SDK mint example and notes numeric guard behavior and backing-token deprecation. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| [], // tokens_to_back | ||
| ) | ||
|
|
||
| await session.transact({ action: { ...mint, authorization: [session.permissionLevel] } }) |
robrigo
force-pushed
the
docs/sdk-accuracy
branch
from
August 18, 2026 05:09
c273fe6 to
6df135d
Compare
robrigo
changed the title
The hosted deployment answers 416 for a collection with no royalty config, not the 404 a reader expects from a missing resource, and on WAX mainnet it answers 416 for every collection because V1 carries no royalty configuration at all. A client that reads 416 as a per-collection fact reads a chain-wide absence as one. The same deployment serves two sales list routes whose rows and filters match, while its own OpenAPI document describes only the newer one, so a generated client and a hand-written one disagree about which route exists. Whether that newer route omits waiting sales is the one claim neither a source read nor a live probe settles: no waiting sale exists on either chain to tell the two apart. It sits in the learning tier with the check that would settle it, and the reference page states the routes without it.
This is the page that teaches URL construction, and it built every example by hand without saying that a caller-supplied id or filter key has to be encoded first. An unencoded slash in an asset id escapes its own path segment and sends the request somewhere else, and an unencoded ampersand in a data-filter key appends parameters of its own. Both SDK clients close that hole, so a hand-rolled equivalent that does not is now the weaker path. The testnet guidance had the opposite problem. Switching chains means swapping two hosts rather than one, and an integrator who changes only the RPC node reads an unrelated chain while every request succeeds. That is the first thing a testnet reader needs and it sat in an unheaded preamble paragraph, so it becomes a section with the host pairs in a table.
The page described 2.0.0 while the package ships 2.1.0, and two of its sentences were false rather than merely stale. Constructing an ExplorerApi no longer fires a config request, so an integrator who designed around a boot-time fetch designed around nothing; the action surface is a read-only getter that fetches on first use and retries after a failure. And transfer takes from and to, so there are no account_from and account_to parameters left to remap. What 2.1.0 added has to be here too, because each failure it prevents is silent. The numeric guards throw naming the offending field, since a NaN reaches a signing library as null with the mistake already erased. Native backing is deprecated on both the action and the mint parameter, where a call that still works means the chain has not migrated rather than that the path is supported. Path segments and both sides of every query pair are percent-encoded. The getter inventory was a paragraph nobody reads and everybody scans, so it becomes a method, route, and return table. The one-object return shape is stated against the market builder's arrays, which is the asymmetry a caller composing both packages trips on first.
The page said the action layer covers the v2 royalty configuration only and not the trade actions. That was true at 2.0.0 and false at 2.3.0, where the builder carries the sale, auction, buyoffer, template-buyoffer, RAM and marketplace families beside the six royalty actions, plus five composers. Two contract actions are reachable only through those composers, because each identifies its offer as the globally last row of the assets offers table rather than by an id, and a page that describes neither leaves a reader to discover that from a failed transaction. The royalty guard was inverted as well. The mainnet route answers 416 rather than 404, and the getter maps 416 to null, so a caller guarding for a raised error gets a silent null instead. The settlement math is the addition with the largest downside. Nothing on chain asserts the amount a delphi purchase deposits, the derivation reproduces the contract's truncated double rather than the exact quotient, and deriving the exact floor instead leaves the deposit a unit short. The bundle opt-out flags are named for the same reason: each guards a transaction that commits with the buyer charged and nothing delivered. The getter inventory and the read-path bullets both become tables, and the config sample now shows a deployment that actually runs V2 instead of a V1 version string on a page about the v2 layer.
Every snippet on this page is a hand-written transact payload, which suits a contract guide and left the corpus with no page showing the builder in context. The same mint now appears both ways, so a reader sees that the builder produces the identical action object and signs nothing. The builder's numeric guards belong with it. A NaN template id has no JSON form and reaches a signing library as null, so the caller's mistake is gone before the chain can name it, and a fractional max_supply serializes intact and surfaces in an error that names neither the call nor the field. Both throw at the call instead.
None of the three guides named either SDK, so every multi-action flow they walk was left for the reader to assemble: the ordering, the memo literals, and which contract owns which action. A composer now encodes each one, and the guide that walks the flow by hand is where a reader looks for it. Two of them carry a throw with nowhere to land. A bundle purchase and a bundle accept both commit under V2 with the buyer charged and nothing delivered, so the composers refuse them behind an opt-out meant only for a chain still running V1. Naming those flags here gives a reader who hits the throw a page that explains it. settlement_quantity appeared nowhere in the corpus at all, and it is the first thing a delphi integrator gets wrong. Nothing on chain checks the deposit: assertsale pins the listing terms and says nothing about the amount or the symbol, so a cross-symbol sale needs a quantity in the settlement symbol and a same-symbol sale needs one equal to the listing price with the median at zero.
Both SDK pins named a main-branch commit at 2.0.0, and both packages now ship a tagged release, so the ledger names the tag and the commit it resolves to. Every row that draws on those pins says which of its facts came from the source read and which from a live endpoint, because the two SDK pages mix them freely and a reader cannot tell from the tier letter alone. No tier moves. The SDK additions across the guides are all source-read, and the live probes behind the API reference sit on pages already tiered both. Where an earlier execution stands behind a fact and only the signature was re-read at the new pin, the row says so rather than implying the run happened again.
Both SDKs now refuse an empty or dot path id before a request leaves, and the market SDK grew a read layer over the settled royalty payout ledger, so the two pages described a surface the published packages no longer have. A reader would have rebuilt royalty reporting by paging settlement logs, and would have expected a bad id to arrive as an ApiError instead of as a plain Error raised before any request exists. The market page also carries the note that the royalty config and rule rows now require market_contract, collection_name, timestamps, and lookup_hash, which is the one break in 2.4.0: reading a response is unaffected, but code that builds such a row by hand no longer compiles. Every citation was re-read at the new commit and moved only where the cited lines moved, which also surfaced getTemplateStats naming its second parameter id rather than name. The payout facts are live as well as read: the testnet routes answer with rows matching the declared types field for field, and the same routes on WAX mainnet answer empty, which is what a chain still on AtomicMarket V1 gives.
The ledger pins one baseline per repository and each guide names the tag its SDK examples were read at, so leaving either behind would point a reader at a tree the reference pages no longer describe. Nothing these guides cite moved: the action builders, the delphi helpers, and the symbol parser are byte-identical between the old and new tags, so only the pin changes and the walkthroughs stand as written.
robrigo
force-pushed
the
docs/sdk-accuracy
branch
from
August 18, 2026 20:07
b1bbe98 to
9f7823a
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Both SDK reference pages described 2.0.0 while the published packages are
@atomichub/atomicassets2.1.0 and@atomichub/atomicmarket2.3.0, and four of their sentences were false rather than stale: the market builder was said to cover royalty configuration only (it carries 26 action builders and five composers), the mainnet royalty routes were said to raise on 404 (they answer 416 and the getter returns null, so the guard advice was inverted), constructing an explorer client was said to fire a config request (it does not), andtransferwas said to remap parameters it does not have. This pull request rewrites both pages to the shipped surface with the export surface as tables and every new fact cited to a file and line at the pinned commit; points the three market guides at the composers beside the raw flows, with the two bundle opt-outs and thesettlement_quantityrules an integrator trips first; adds a worked builder mint to the creator-flow guide; corrects the royalty status code and names the second sales route on the API page; and moves the ledger's SDK baselines onto the shipped tags. One claim the design made about the materialized sales route could not be verified in source or by a live probe and is filed underlearning/with the check that would settle it, rather than asserted.Notes for the maintainer
Stacked on the CI pull request so every check runs on arrival. Facts are graded honestly in the ledger: source-read where only the source was read, live-chain where an endpoint was probed. The commits are unsigned; the squash merge carries GitHub's signature.