docs: cover the sdk, vert testing, and thin protocol surfaces#1
Merged
Conversation
R1 documented the contracts and API but left the client side untaught: the official SDKs had no page at all, vert was referenced but never explained, and atomictools, media conventions, the socket surface, and rate limits were thin or absent. Nine new pages close those gaps, each validated against pinned source or live reads per the repo's process, with executable snippets that were actually run. Two live-verified corrections ride along: the API's mediatype synthesis exists only on the 2.0.0 line, and template buyoffers broadcast no socket events at the pinned commit.
There was a problem hiding this comment.
Pull request overview
This PR expands the repository’s validated documentation to cover client-side and integrator surfaces that were previously missing or thin, including the official JS/TS SDKs, VeRT-based contract testing, AtomicTools claim links, media conventions, API streaming (Socket.IO), and REST rate limits. It also updates the routing table, README scope map, and validation log to reflect the added coverage and source pins.
Changes:
- Add new reference pages for
@atomichub/atomicassetsand@atomichub/atomicmarketSDK surfaces, plus new docs for media conventions and Socket.IO streaming. - Add new guides for AtomicTools claim links, reactive
on_notifyintegrations, and contract testing with@atomichub/vert. - Update
AGENTS.md,README.md, andvalidation-log.mdto route agents correctly and record validation pins/tiers for the new pages.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| validation-log.md | Adds new baselines and validation rows for the newly documented SDK/streaming/tools/vert surfaces; updates tier distribution. |
| reference/sdk/atomicmarket.md | New SDK reference for market reads, v2 royalties reads, and royalty-config action building. |
| reference/sdk/atomicassets.md | New SDK reference for explorer/rpc reads, serialization helpers, and v2 action building patterns. |
| reference/media.md | New reference documenting de-facto media field conventions and robust IPFS/URL resolution behavior. |
| reference/atomictools/tables.md | New AtomicTools table reference (links/config), including live-read examples and index semantics. |
| reference/atomictools/actions.md | New AtomicTools action reference, including funding via on_notify and signature-based claims. |
| reference/atomicassets/tables.md | Updates schematypes caveat with versioned behavior about API mediatype/info synthesis. |
| reference/api.md | Adds a rate-limits section; updates template buyoffer socket notes to reflect unwired handler at pinned commit. |
| reference/api-streaming.md | New reference for the atomicassets-api Socket.IO surface: namespaces, events, rooms, and limits. |
| README.md | Expands README “Area”/“Organization” summaries to include SDKs, media, testing, tools, streaming/rate limits. |
| guides/testing-with-vert.md | New guide for in-process contract testing with @atomichub/vert, including known emulation limits. |
| guides/notification-integration.md | New guide for integrating with AtomicAssets notifications and safe handler patterns. |
| guides/links.md | New end-to-end guide for AtomicTools claim links: announce, fund-by-transfer, claim-by-signature, cancel, and reads. |
| AGENTS.md | Updates routing table to include new domains/pages (tools, media, SDKs, streaming, vert, integration). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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
R1 documented the contracts, indexer, and API but left the client side untaught. The official SDKs (@atomichub/atomicassets, @atomichub/atomicmarket) had no coverage, vert was referenced but never explained, and atomictools, media conventions, the realtime socket surface, and rate limits were thin or missing. Nine new pages close those gaps: SDK references, a vert testing guide, the atomictools claim-link reference and guide, media conventions, API streaming, a rate-limits section, and a positive on_notify integration guide.
Validation
Every page follows the repo's validation process: facts cited to pinned source (atomictools d89ce79e4, SDK mains at 2.0.0, vert 2.2.0, atomicassets-api f6419858) or live reads, with each executable snippet actually run (live API reads on WAX mainnet and testnet, a Socket.IO handshake probe of five namespaces, the deployed atomictoolsx ABI diffed against pinned source, vert's suite plus purpose-built probe contracts). Validation-log rows, routing table, and README coverage updated; tier distribution recounted at 36 pages. Two live-verified corrections ride along: mediatype synthesis is 2.0.0-only behavior, and template buyoffers broadcast no socket events at the pinned commit.