From f47c96ea6495e862aaff65c6728bf70bd61c5813 Mon Sep 17 00:00:00 2001 From: Robrigo <590263+robrigo@users.noreply.github.com> Date: Sun, 2 Aug 2026 20:06:07 +0000 Subject: [PATCH] docs: use the protocol's own vocabulary for the asset category The contract, table, and API vocabulary never uses the industry category label; describing assets in the protocol's own nouns is more precise and keeps the corpus consistent with the sources it cites. Sixteen prose lines across eleven files swap the category label for asset-based phrasing; no fenced snippet, identifier, error string, or technical claim changes. The settlement actions' movement labels now read as the consistent pair Token movement and Asset movement. --- AGENTS.md | 2 +- README.md | 4 ++-- guides/asset-lifecycle.md | 2 +- guides/links.md | 4 ++-- reference/atomicassets/backing-tokens.md | 2 +- reference/atomicassets/structure.md | 2 +- reference/atomicmarket/actions.md | 6 +++--- reference/atomictools/actions.md | 2 +- reference/media.md | 4 ++-- reference/sdk/atomicassets.md | 2 +- skills/atomic-integration/SKILL.md | 2 +- 11 files changed, 16 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 20a79cd..11abed2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ Start here. Identify the domain the task touches, then read the matching file be | AtomicAssets V2 upgrade and indexer/chain compatibility | `reference/atomicassets/v2-upgrade.md` | | AtomicTools claim-links action reference: announce, fund, claim, cancel, the signature claim mechanism | `reference/atomictools/actions.md` | | AtomicTools tables (links, config): schema, scope, the assetidshash index | `reference/atomictools/tables.md` | -| NFT media: IPFS references, field-name conventions (img/backimg/video), bare-CID vs URL parsing, gateway resolution, V2 media-type descriptors | `reference/media.md` | +| Asset media: IPFS references, field-name conventions (img/backimg/video), bare-CID vs URL parsing, gateway resolution, V2 media-type descriptors | `reference/media.md` | | Calling atomicassets-api HTTP endpoints: pagination limits, buyoffer lifecycle states, rate limits | `reference/api.md` | | atomicassets-api realtime/streaming: Socket.IO namespaces, events, room subscription, socket auth and limits | `reference/api-streaming.md` | | Running or extending the atomicassets-api indexer (also known as eosio-contract-api): handler configuration, drain gating, data freshness, migrations, CI | `reference/atomicassets-api.md` | diff --git a/README.md b/README.md index c4aaa77..e4df10a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Atomic Knowledge -Validated, source-cited knowledge for building on the Atomic NFT ecosystem on WAX and other Antelope chains: the AtomicAssets and AtomicMarket smart contracts, the atomicassets-api (eosio-contract-api) indexer, and the chain and client-library behavior around them. +Validated, source-cited knowledge for building on the Atomic ecosystem on WAX and other Antelope chains: the AtomicAssets and AtomicMarket smart contracts, the atomicassets-api (eosio-contract-api) indexer, and the chain and client-library behavior around them. Every statement in this repository was validated against contract or indexer source code, or against live chain reads, before inclusion. The material is aimed at developers and coding agents building Atomic integrations: marketplaces, wallets, indexers, bots, and tooling. @@ -13,7 +13,7 @@ Every statement in this repository was validated against contract or indexer sou | API | The hosted atomicassets-api endpoints (e.g. wax.api.atomicassets.io): pagination limits, lifecycle states, query semantics, rate limits, and the Socket.IO realtime surface | | Chain and clients | nodeos RPC behavior, error semantics, and @wharfkit/antelope client-library behavior | | SDKs | The official @atomichub/atomicassets and @atomichub/atomicmarket JavaScript/TypeScript clients: typed API and chain-table reads, attribute serialization, and V2 action building | -| Media | How NFT media is referenced on chain (bare IPFS CIDs under de-facto img/backimg/video fields), value-shape parsing, and gateway resolution | +| Media | How asset media is referenced on chain (bare IPFS CIDs under de-facto img/backimg/video fields), value-shape parsing, and gateway resolution | | Testing | Running compiled Antelope contracts in-process with @atomichub/vert (VeRT): action calls, table reads, time control, the per-chain host-function gate, and the emulation's limits | ## Organization diff --git a/guides/asset-lifecycle.md b/guides/asset-lifecycle.md index cdbcc33..bd49ecb 100644 --- a/guides/asset-lifecycle.md +++ b/guides/asset-lifecycle.md @@ -4,7 +4,7 @@ depends-on: [reference/atomicassets/structure.md, reference/atomicassets/actions key-modules: ["atomicmarket-contract (v2.0.0-rc2): src/atomicmarket.cpp", "atomicassets-contract (v2.0.0-rc4): src/atomicassets.cpp"] --- -# Asset lifecycle: creating and managing AtomicAssets NFTs +# Asset lifecycle: creating and managing assets The full creator flow on the `atomicassets` contract: create a collection, define a schema, optionally create a template, mint assets, edit mutable data, transfer, and burn. Baseline is AtomicAssets V2; notes call out where V1 differed. Every data shape, required authorization, RAM payer, and failure mode below was checked against tag `v2.0.0-rc4` of `atomicassets-contract` (the release pinned for both testnets), `src/atomicassets.cpp`. diff --git a/guides/links.md b/guides/links.md index 3d0dea4..9ff78d5 100644 --- a/guides/links.md +++ b/guides/links.md @@ -6,7 +6,7 @@ key-modules: ["atomictools-contract (commit d89ce79e4): src/link.cpp, include/at # Links: the atomictools claim-link flow -A claim link (or "claimlink") lets someone hand a set of AtomicAssets NFTs to a recipient who does not yet have an account name in hand: the sender escrows the assets against an off-chain key pair, and whoever receives the private key can claim the assets to any account they control. It is how "here is a link, open it to receive these NFTs" flows are built on Antelope chains. The contract is deployed as account `atomictoolsx` on WAX and under the same name on other chains; the `config.atomicassets_account` it escrows through is `atomicassets`. +A claim link (or "claimlink") lets someone hand a set of assets to a recipient who does not yet have an account name in hand: the sender escrows the assets against an off-chain key pair, and whoever receives the private key can claim the assets to any account they control. It is how "here is a link, open it to receive these assets" flows are built on Antelope chains. The contract is deployed as account `atomictoolsx` on WAX and under the same name on other chains; the `config.atomicassets_account` it escrows through is `atomicassets`. The contract has no release tags. Source citations pin commit `d89ce79e4` of `pinknetworkx/atomictools-contract`. This guide shows each write as plain JSON action data first, then the same call through `@wharfkit/session`'s `session.transact()`; it does not broadcast any transaction. The read examples are live `get_table_rows` and hosted-API calls that were run read-only against `wax.greymass.com` and `wax.api.atomicassets.io`. Asset ids and the `link_counter` exceed the JavaScript safe-integer range and must be passed as strings; see `reference/wharfkit.md` and `reference/atomicmarket/v2-changes.md` ("Large integers serialize as strings"). @@ -168,7 +168,7 @@ Source: `src/link.cpp:107-124` ## RAM and authorization notes - The `links` row RAM is paid by the creator from `announcelink` onward and released when the link is claimed or cancelled. Funding the link (`assets_transferred` flip) keeps the same payer, so a claim does not shift RAM cost onto the recipient for the link row itself. -- The escrowed NFTs live in the `atomictoolsx` account's own AtomicAssets scope between funding and resolution. The contract moves them out under `permission_level{atomictoolsx, "active"}`, so the deployed account's `active` permission must be able to call `atomicassets::transfer` (it is the contract's own authority, so this holds by default). +- The escrowed assets live in the `atomictoolsx` account's own AtomicAssets scope between funding and resolution. The contract moves them out under `permission_level{atomictoolsx, "active"}`, so the deployed account's `active` permission must be able to call `atomicassets::transfer` (it is the contract's own authority, so this holds by default). - A first-time recipient's new asset scope RAM is paid by `atomictoolsx` on claim, since the contract is the transfer sender. - The unrelated `auth` action always throws by design; it is a proof-of-key-control challenge for off-chain services, not part of the link flow. See `reference/atomictools/actions.md` ("Admin and off-chain auth"). diff --git a/reference/atomicassets/backing-tokens.md b/reference/atomicassets/backing-tokens.md index 39e971d..50ae8c7 100644 --- a/reference/atomicassets/backing-tokens.md +++ b/reference/atomicassets/backing-tokens.md @@ -16,7 +16,7 @@ Source: `src/atomicassets.cpp:990-1032` (announcedepo), `src/atomicassets.cpp:14 ## The balances table is a general-purpose deposit ledger -`balances_s` is one row per owner holding a vector of `asset` quantities, one entry per announced symbol, with no link to any specific NFT. `withdraw` spends directly out of this pool back to the owner's wallet through the token contract recorded in `supported_tokens`. Historically `backasset` spent out of the same pool to attach value to an asset. The table itself is not backing-specific; it is whatever pre-funded balance any contract action needs. +`balances_s` is one row per owner holding a vector of `asset` quantities, one entry per announced symbol, with no link to any specific asset. `withdraw` spends directly out of this pool back to the owner's wallet through the token contract recorded in `supported_tokens`. Historically `backasset` spent out of the same pool to attach value to an asset. The table itself is not backing-specific; it is whatever pre-funded balance any contract action needs. Source: `include/atomicassets.hpp:445-451` (`balances_s`), `src/atomicassets.cpp:1040-1070` (withdraw), `src/atomicassets.cpp:1768-1801` (internal_decrease_balance) diff --git a/reference/atomicassets/structure.md b/reference/atomicassets/structure.md index 28ec09b..75ae9bc 100644 --- a/reference/atomicassets/structure.md +++ b/reference/atomicassets/structure.md @@ -6,7 +6,7 @@ key-modules: ["atomicassets-contract (v2.0.0-rc4): src/atomicassets.cpp, include # AtomicAssets data model structure -The `atomicassets` contract organizes NFTs in four levels: collections group schemas and templates and hold the authorization rules, schemas declare the attribute formats a collection's data serializes to, templates carry immutable data shared by many assets, and assets are the individual token instances. Baseline behavior below is V2, tag `v2.0.0-rc4` of `atomicassets-contract` (the release pinned for both testnets: `include/atomicassets.hpp`, `src/atomicassets.cpp`); "Changed in V2" notes call out where V1 differs enough to matter to an integrator. +The `atomicassets` contract organizes assets in four levels: collections group schemas and templates and hold the authorization rules, schemas declare the attribute formats a collection's data serializes to, templates carry immutable data shared by many assets, and assets are the individual token instances. Baseline behavior below is V2, tag `v2.0.0-rc4` of `atomicassets-contract` (the release pinned for both testnets: `include/atomicassets.hpp`, `src/atomicassets.cpp`); "Changed in V2" notes call out where V1 differs enough to matter to an integrator. ## Collections diff --git a/reference/atomicmarket/actions.md b/reference/atomicmarket/actions.md index e64a224..99e1598 100644 --- a/reference/atomicmarket/actions.md +++ b/reference/atomicmarket/actions.md @@ -263,7 +263,7 @@ Source: `include/atomicmarket.hpp:195-197`, `src/atomicmarket.cpp:838-885` For a legacy multi-asset sale row (`asset_ids.size() > 1`), this call cancels the listing instead of purchasing it and charges the buyer nothing. For a normal single-asset sale: asserts the buyer is not the seller, the sale has an active backing offer, and the taker marketplace is registered; computes the settlement price (resolving the Delphi median if applicable); decreases the buyer's internal balance by that price; runs the full payout split (see `internal_payout_sale`, cross-linked below); accepts the AtomicAssets offer and transfers the assets to the buyer; erases the sale row. -Token/asset movement: buyer's internal balance -> maker/taker marketplace balances, collection royalty split balances, bonus fee balances, and the seller's balance (immediately withdrawn to a real token transfer to the seller). NFT: AtomicAssets offer accepted, asset moves seller -> buyer. +Token movement: buyer's internal balance -> maker/taker marketplace balances, collection royalty split balances, bonus fee balances, and the seller's balance (immediately withdrawn to a real token transfer to the seller). Asset movement: AtomicAssets offer accepted, asset moves seller -> buyer. Source: `include/atomicmarket.hpp:199-204`, `src/atomicmarket.cpp:896-981` @@ -382,7 +382,7 @@ Source: `include/atomicmarket.hpp:256-258`, `src/atomicmarket.cpp:1501-1513` For a legacy multi-asset buyoffer, this cancels the buyoffer and refunds the buyer instead of trading (identical outcome to `declinebuyo`). For a normal single-asset buyoffer: requires the most recently created AtomicAssets offer to be exactly `recipient -> atomicmarket`, offering only the buyoffer's asset, asking for nothing, with memo `"buyoffer"`. Accepts that offer, transfers the asset to the buyer, and runs the payout split on the escrowed price, crediting/withdrawing to the recipient (the erstwhile seller). -Token/asset movement: escrowed buyer balance -> maker/taker/collection royalty/bonus fee balances and the recipient's withdrawn balance. NFT: recipient -> buyer via the accepted AtomicAssets offer. +Token movement: escrowed buyer balance -> maker/taker/collection royalty/bonus fee balances and the recipient's withdrawn balance. Asset movement: recipient -> buyer via the accepted AtomicAssets offer. Source: `include/atomicmarket.hpp:260-265`, `src/atomicmarket.cpp:1533-1626` @@ -429,7 +429,7 @@ Source: `include/atomicmarket.hpp:294-296`, `src/atomicmarket.cpp:1703-1715` Requires the most recently created AtomicAssets offer to be exactly `seller -> atomicmarket`, offering only `asset_id`, asking for nothing, with memo `"tbuyoffer"`. Accepts that offer, transfers the asset to the buyer, and runs the payout split on the escrowed price, crediting/withdrawing to `seller`. Erases the row. -Token/asset movement: escrowed buyer balance -> maker/taker/collection royalty/bonus fee balances and the seller's withdrawn balance. NFT: seller -> buyer via the accepted AtomicAssets offer. +Token movement: escrowed buyer balance -> maker/taker/collection royalty/bonus fee balances and the seller's withdrawn balance. Asset movement: seller -> buyer via the accepted AtomicAssets offer. Source: `include/atomicmarket.hpp:308-314`, `src/atomicmarket.cpp:1717-1794` diff --git a/reference/atomictools/actions.md b/reference/atomictools/actions.md index 68144eb..d75267a 100644 --- a/reference/atomictools/actions.md +++ b/reference/atomictools/actions.md @@ -8,7 +8,7 @@ key-modules: ["atomictools-contract (commit d89ce79e4): src/link.cpp, src/auth.c Complete action reference for the `atomictools` contract, deployed as account `atomictoolsx` on WAX (and under the same account name on other Antelope chains). The contract has no release tags; every citation below pins commit `d89ce79e4` of `pinknetworkx/atomictools-contract`. Action declarations are in `include/atomictoolsx.hpp`; bodies are in `src/link.cpp` and `src/auth.cpp`. -The contract's single purpose is transferable claim links: a creator escrows a set of AtomicAssets NFTs against an off-chain key pair, and anyone who holds the matching private key can later claim those assets to their own account. It moves no fungible tokens and holds no balances of its own; the only assets it ever custodies are the escrowed NFTs, held in the `atomictoolsx` account's own AtomicAssets scope between announcement and claim/cancel. +The contract's single purpose is transferable claim links: a creator escrows a set of assets against an off-chain key pair, and anyone who holds the matching private key can later claim those assets to their own account. It moves no fungible tokens and holds no balances of its own; the only assets it ever custodies are the escrowed ones, held in the `atomictoolsx` account's own AtomicAssets scope between announcement and claim/cancel. Live-chain status: the full action and table list on this page was diffed against the deployed `atomictoolsx` ABI on WAX mainnet (`get_abi`) and matches the pinned source exactly. `config.version` reads `1.0.0` live. diff --git a/reference/media.md b/reference/media.md index a0c202a..7d40a5b 100644 --- a/reference/media.md +++ b/reference/media.md @@ -1,5 +1,5 @@ --- -scope: How NFT media is referenced in the Atomic ecosystem - IPFS storage, de-facto media field-name conventions, bare-CID vs URL handling, and gateway resolution +scope: How asset media is referenced in the Atomic ecosystem - IPFS storage, de-facto media field-name conventions, bare-CID vs URL handling, and gateway resolution depends-on: - reference/atomicassets/serialization.md - reference/atomicassets/custom-types.md @@ -9,7 +9,7 @@ key-modules: ["atomicassets-contract (v2.0.0-rc4): include/atomicdata.hpp (image # Media conventions -How an Atomic NFT points at its media, and what an integrator must do to render it. The chain stores no image bytes and no media column: media is carried as ordinary schema attributes whose values are IPFS references, under field names that are collection convention rather than contract rule. This page covers those conventions and how to resolve them. The wire encoding of the `ipfs` and `image` FORMAT types is in `reference/atomicassets/serialization.md`; the V2 `FORMAT_TYPE` media-type mechanism is in `reference/atomicassets/custom-types.md`; which data layer a given attribute comes from is in `reference/atomicassets/data-precedence.md`. This file does not restate those. +How an Atomic asset points at its media, and what an integrator must do to render it. The chain stores no image bytes and no media column: media is carried as ordinary schema attributes whose values are IPFS references, under field names that are collection convention rather than contract rule. This page covers those conventions and how to resolve them. The wire encoding of the `ipfs` and `image` FORMAT types is in `reference/atomicassets/serialization.md`; the V2 `FORMAT_TYPE` media-type mechanism is in `reference/atomicassets/custom-types.md`; which data layer a given attribute comes from is in `reference/atomicassets/data-precedence.md`. This file does not restate those. ## Media is attribute data, not a dedicated field diff --git a/reference/sdk/atomicassets.md b/reference/sdk/atomicassets.md index 1e56d16..1731ddf 100644 --- a/reference/sdk/atomicassets.md +++ b/reference/sdk/atomicassets.md @@ -7,7 +7,7 @@ key-modules: # @atomichub/atomicassets SDK -The official JavaScript/TypeScript client for the AtomicAssets NFT standard on Antelope chains. It reads NFT data over the hosted API and directly from chain tables, serializes and deserializes attribute data, and builds v2 contract actions for a signer to sign. Version-sensitive facts below were read from the 2.0.0 source tree; re-verify against current source after an upgrade. +The official JavaScript/TypeScript client for the AtomicAssets standard on Antelope chains. It reads asset data over the hosted API and directly from chain tables, serializes and deserializes attribute data, and builds v2 contract actions for a signer to sign. Version-sensitive facts below were read from the 2.0.0 source tree; re-verify against current source after an upgrade. ``` npm install @atomichub/atomicassets diff --git a/skills/atomic-integration/SKILL.md b/skills/atomic-integration/SKILL.md index d357206..c878c2d 100644 --- a/skills/atomic-integration/SKILL.md +++ b/skills/atomic-integration/SKILL.md @@ -10,7 +10,7 @@ key-modules: [] ## When to use -Use this skill whenever the task touches the Atomic NFT ecosystem on WAX/Antelope chains: listing or trading through the AtomicMarket contract, reading AtomicAssets state, calling atomicassets-api endpoints, running or extending the atomicassets-api indexer, deploying contract releases, or reading chain tables and accounts through @wharfkit/antelope or raw RPC. +Use this skill whenever the task touches the Atomic ecosystem on WAX/Antelope chains: listing or trading through the AtomicMarket contract, reading AtomicAssets state, calling atomicassets-api endpoints, running or extending the atomicassets-api indexer, deploying contract releases, or reading chain tables and accounts through @wharfkit/antelope or raw RPC. ## Steps