diff --git a/astro.config.mjs b/astro.config.mjs index 7bc8aff..b670934 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -115,6 +115,10 @@ export default defineConfig({ { label: 'Task: manage assets from Portfolio', slug: 'portfolio/manage-assets' }, ], }, + { + label: 'Create', + items: [{ label: 'Atomicals Studio', slug: 'create/atomicals-studio' }], + }, { label: 'Markets', items: [ diff --git a/public/llms.txt b/public/llms.txt index 8994589..2a3cb1d 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -61,6 +61,10 @@ not production availability, and a parser existing is not wallet support. - [Marketplace v1 gates](https://bitcoinuniverseio.github.io/docs-core/markets/marketplace-v1/) - [Collection media](https://bitcoinuniverseio.github.io/docs-core/markets/collection-media/) +## Create + +- [Atomicals Studio](https://bitcoinuniverseio.github.io/docs-core/create/atomicals-studio/): create and move ARC-20 tokens, NFTs, Realms, Subrealms, Containers, and DMINT items. + ## Data provenance - [Where each number comes from](https://bitcoinuniverseio.github.io/docs-core/data/provenance/) diff --git a/scripts/build-assets.mjs b/scripts/build-assets.mjs index 045a1d9..0382b4e 100644 --- a/scripts/build-assets.mjs +++ b/scripts/build-assets.mjs @@ -134,6 +134,10 @@ it is implemented and switched off unless an operator enables it. - [Marketplace v1 gates](${SITE}/markets/marketplace-v1/) - [Collection media](${SITE}/markets/collection-media/) +## Create + +- [Atomicals Studio](${SITE}/create/atomicals-studio/): create and move ARC-20 tokens, NFTs, Realms, Subrealms, Containers, and DMINT items. + ## Data provenance - [Where each number comes from](${SITE}/data/provenance/) diff --git a/src/content/docs/create/atomicals-studio.mdx b/src/content/docs/create/atomicals-studio.mdx new file mode 100644 index 0000000..a46e693 --- /dev/null +++ b/src/content/docs/create/atomicals-studio.mdx @@ -0,0 +1,131 @@ +--- +title: Atomicals Studio +description: >- + Creating and moving Atomicals on bitcoinuniverse.io: the seven tool families, + the address of every tool, which wallet signs each one, and how a commit and + reveal run. +sidebar: + order: 1 +--- + +import Provenance from '../../../components/Provenance.astro'; + + + +Atomicals Studio is where you create and move Atomicals, on the main +application at +[`bitcoinuniverse.io/atomicals/create`](https://bitcoinuniverse.io/atomicals/create). +It runs on that site: your browser does not leave it, and nothing is signed +anywhere except in your own wallet. + +## What you can do + +Every tool has its own address, `/atomicals/create//`, so a +tool can be bookmarked, linked, and reopened. + +| Family | Actions | Address | +| --- | --- | --- | +| ARC-20 | Deploy, Mint, Transfer, Fixed supply | `/atomicals/create/arc20/deploy`, `mint`, `transfer`, `issue` | +| NFT | Mint, Transfer | `/atomicals/create/nft/mint`, `transfer` | +| Realm | Claim, Transfer | `/atomicals/create/realm/claim`, `transfer` | +| Subrealm | Claim, Pay, Transfer | `/atomicals/create/subrealm/claim`, `pay`, `transfer` | +| Container | Create, Configure, Seal | `/atomicals/create/container/create`, `configure`, `seal` | +| DMINT item | Mint, Transfer | `/atomicals/create/dmitem/mint`, `transfer` | +| Manage | Update, Event, Separate | `/atomicals/create/manage/update`, `event`, `separate` | + +**Fixed supply** issues an ARC-20 token whose whole supply is created at once. +**Manage** updates an Atomical's state or records an event on it. + +**Separate** gives each NFT that shares one Bitcoin output its own output at +your address. A direct Subrealm claim needs it: the claim spends the parent +Realm, and the Atomicals index then keeps the parent and the new Subrealm on +the same output. While they share it, Studio refuses to update, transfer or +claim with either one and links to Separate with the Atomical filled in. +Separate orders the outputs the way the index does, lists which NFT goes to +which output before you sign, and refuses an output that also holds an ARC-20 +balance, which it could not carry over safely. + +If your wallet has no confirmed plain Bitcoin output large enough for an +operation, Studio says so and names the amount needed. It is not reported as +a service outage. + +**DMINT item** mints follow the container's rules. When the rule that +matches the item asks for a payment, Studio reads it from the index first and +shows every amount and payee before anything is signed. The button then reads +**Authorize mint and payment**, and your wallet signs exactly that payment +with the mint. If the container owner changes the rules before you sign, the +mint is refused with that reason and nothing is paid. + +A tool the server cannot run right now stays visible and says +**Unavailable**, with the reason. Nothing you press on an unavailable tool +creates a transaction. + +## Which wallet signs + +Studio never holds a key. Each step opens your wallet, and the wallet is the +final authorization. + +| Tools | Wallet | +| --- | --- | +| NFT, Realm, Subrealm, Container configure, Manage | [Wizz Wallet](/docs-core/wallets/connecting/) | +| ARC-20 deploy, mint, transfer | Any wallet Core supports | +| ARC-20 fixed supply, Container create and seal, DMINT item mint and transfer | A wallet that reports its network and account explicitly | + +Before anything is prepared, Studio checks that the wallet is on the network +the service runs on. If Wizz reports another network, Studio asks you to +switch it and prepares nothing. If the Wizz account is not the one you +connected, Studio asks you to reconnect. + +## How a creation runs + +Most Atomicals operations take two transactions: a **commit**, then a +**reveal** that spends it once the commit is confirmed. + +1. Open the tool and fill in the form. +2. Review what Studio prepared. Nothing has been signed yet. +3. Sign the commit in your wallet. Studio checks that the signed transaction + is the one it prepared before it is sent. +4. Wait for the commit to confirm. The tracker shows the stage it is in. +5. Sign the reveal in your wallet as soon as the commit confirms. See + [the reveal window](#the-reveal-window). +6. The tracker shows **Done** once the result is indexed. + +Operations you start are listed on the page, and stay listed after a reload. +Open one to see its stage or to continue it. The list, and what Studio needs +to continue an operation, are kept in this browser, so you can close the tab +and come back later in the same browser to finish, for example to pay for a +Subrealm claim. Another browser or device cannot continue it. + +A failed, cancelled, or expired operation says so. It is never shown as +complete. + +## The reveal window + +The Atomicals index creates a Realm or Subrealm only when its reveal is mined +within **3 blocks** of the commit, and an NFT within **100 blocks**. A later +reveal would confirm and create nothing. Once the window has closed, the server +refuses the reveal (`REVEAL_WINDOW_CLOSED`) and the operation expires, so +Studio no longer offers it. + +For a Realm or direct Subrealm claim, Studio offers the reveal as soon as the +commit is in the mempool, so both can confirm in the same block. Sign it +then; a network that mines several blocks in quick succession can close a +3-block window in minutes. + +## Coming from `/inscribe` + +`bitcoinuniverse.io/inscribe` is an ordinary page, not a redirect. It links to +Atomicals Studio, and to the separate Inscribe application for other +protocols. Inscribe opens only when you follow that link. + +## Next + +- [Atomicals markets](/docs-core/markets/atomicals/), to trade what you created +- [Connecting a wallet](/docs-core/wallets/connecting/) +- [Transaction safety](/docs-core/wallets/transaction-safety/) diff --git a/src/content/docs/markets/atomicals.mdx b/src/content/docs/markets/atomicals.mdx index 2042dbc..61629c7 100644 --- a/src/content/docs/markets/atomicals.mdx +++ b/src/content/docs/markets/atomicals.mdx @@ -12,11 +12,11 @@ import Provenance from '../../../components/Provenance.astro'; Atomicals is the largest enabled family in Core: four of the nine `enabled` @@ -37,6 +37,84 @@ routes and durable state. A browse result does not by itself mean an asset is listed for sale. +## Where each market is + +| Market | Address | Protocol and asset type | +| --- | --- | --- | +| ARC-20 | `/trade/arc20` | `arc20`. The asset ID is the ticker | +| Atomicals NFTs | `/trade/atomicals/nfts` | `atomicals_nft`, type `nft` | +| Containers | `/trade/atomicals/containers` | `atomicals_nft`, type `container` | +| DMINT items | `/trade/atomicals/items` | `atomicals_nft`, type `dmitem` | +| Realms | `/trade/atomicals/realms` | `realms` | +| Subrealms | `/trade/atomicals/subrealms` | `subrealms` | + +Containers and DMINT items trade under the NFT protocol, and each market shows +only its own type. + +Realm, Subrealm, Container, and DMINT item rows show the Atomical's name. Plain +NFTs, and listings created before names were recorded, show the Atomical ID. + +## What you can do + +| Action | What happens | +| --- | --- | +| **List** | You set a price per unit and sign in your wallet. The listing opens after the market's checks pass | +| **Update listing** | A new price, recorded as a new revision of the same listing | +| **Delist** | A signed message, not a transaction. The review dialog shows the exact commitment your wallet is asked to sign | +| **Buy** | The listing is reserved, the purchase is prepared, you sign it, it is broadcast, and it settles after confirmation | +| **Offers** | Create an offer, cancel your own, or accept one made on an asset you hold | +| **Recovery** | Find out what happened to a request whose answer never arrived. See below | + +## Prices and fees + +A price is always **per unit**. The listing form asks for the **Price per unit +(sats)** and shows the total as you type. A lot's total is its unit price times +its quantity, so 2,000 units at 1,100 sats per unit cost 2,200,000 sats. Market +cards and listing pages show the **Unit price**, and the **Total price** when a +lot holds more than one unit. The wallet review shows both. + +The marketplace fee is worked out on the total and charged to both sides: + +- the seller receives the total minus the fee; +- the buyer pays the total plus the fee, plus the network fee. + +On bitcoinuniverse.io the fee is 1% of the total, and at least 500 sats, on +each side. The smallest total the market accepts is therefore 1,046 sats: a +500-sat fee leaves the seller the 546-sat dust minimum. A sale counts as +settled once its transaction has 6 confirmations. + +The market refuses a price whose payout after the fee would fall below the +Bitcoin dust limit, and says so (`price_below_minimum`). When the wallet's +funds do not cover the total, the fee, and the network fee, it says that too +(`insufficient_funding`) instead of asking you to refresh. The review screen +shows the exact fee and your net proceeds before you sign. + +## When a request times out + +A request can reach the market and apply even though your browser never saw +the answer. When that happens, Core locks that asset and shows **Earlier +request outcome unknown**, with a **Check what happened** button. + +Checking asks the market, with a request signed by your wallet, about the +earlier request under its original request key, so the action can never apply +twice: + +- if the market applied it, the market replays what it recorded and nothing + happens a second time; +- if the market never ran it, the request is closed as not applied; +- if it was the final step of an action you had already signed and the market + never ran it, that same signed step is completed under its original key, + once. + +The lock clears once the market confirms the outcome. When the check proves a +final step applied, the page also clears the unfinished-action notice for the +prepared action that step used. + +This covers every step that finalizes an action: listing, updating, delisting, +buying, creating an offer, and accepting one. Until the check answers, other +actions on that asset stay closed, so a timeout cannot turn into a double +listing or a second purchase. + ## What every mutation rechecks Each mutation rechecks the exact Bitcoin output, the owner script, the spent @@ -49,6 +127,20 @@ listing cannot contain a Realm, Subrealm, fungible token, container, or item subtype. Realm and Subrealm markets additionally require the resolver to return the verified winner at the exact live owner outpoint. +A refusal names its cause when retrying cannot help: + +- **The connected wallet does not hold this asset.** Only the address that + holds it can list or change it. Switch to that wallet. +- **The listed asset has moved.** The seller transferred or spent it, so the + listing can no longer be filled. +- **This wallet's funding is already committed to its open offers or pending + purchases.** Finish or cancel one of them, or add funds. An offer or purchase + otherwise uses whatever funding its other offers and purchases do not hold. + +The market also watches the output behind every open listing, for all +Atomicals types. When that output is spent, even before the spending +transaction confirms, the listing leaves the book. + Prepared transactions must assign the selected Atomical to one **unburned** output, preserve the reviewed seller payout and fees, and pass Bitcoin Core preflight. @@ -58,6 +150,11 @@ configure 1 to 100. Listing revisions, funded offers, reservations, broadcast lineage, confirmation, dropped and replaced transactions, and reorg reconciliation are durable and protocol-scoped. +If relaying a purchase fails, the market asks its own Bitcoin node whether the +transaction went out. A purchase that may have been sent is never reported as +not applied, and a listing is not offered again while a purchase already +broadcast for it is pending or confirmed. + ## Listing an ARC-20 lot An ARC-20 balance is held in complete colored-sat outputs. @@ -65,7 +162,7 @@ An ARC-20 balance is held in complete colored-sat outputs. 1. Open the token from Portfolio or its ARC-20 market. 2. Select one **available lot**. 3. Enter the sale price. -4. Review the 1.5% seller service fee and the net proceeds. +4. Review the marketplace fee and the net proceeds. 5. Approve the PSBT in the connected wallet. Core never splits the selected colored lot and never uses it as ordinary @@ -77,6 +174,10 @@ reads the open listing from the market; retrying cannot create a second open listing for the same ARC-20 outpoint. Buying independently applies the buyer service fee and preserves every colored satoshi in the buyer output. +If another transaction spends a listed lot on other terms, for example because +the seller moved it or it sold elsewhere, a purchase of that lot can never +confirm. Core then closes the lot instead of returning it to the book. + ## NFT artwork Atomicals NFT cards show authoritative inline artwork when the unified index @@ -108,6 +209,7 @@ distinguishable from a genuinely empty market or wallet. ## Next +- [Atomicals Studio](/docs-core/create/atomicals-studio/), to create and move Atomicals - [ARC-20 in the registry](/docs-core/protocols/detail/arc20/) - [Portfolio](/docs-core/portfolio/portfolio/) - [Task: list an asset](/docs-core/markets/list/) diff --git a/src/content/docs/markets/marketplace-v1.mdx b/src/content/docs/markets/marketplace-v1.mdx index 923d005..47cfa37 100644 --- a/src/content/docs/markets/marketplace-v1.mdx +++ b/src/content/docs/markets/marketplace-v1.mdx @@ -137,9 +137,13 @@ separate and keep their own entered prices. ## Before signing +Marketplace v1 prices are per unit, or per item for Ordinals. A listing's total +is its unit price times its quantity, and the review shows the **Unit price** +and the **Total price**. + 1. Confirm the wallet network and connected account. -2. Review the protocol, asset identity, quantity, price, fees, inputs, and - outputs. +2. Review the protocol, asset identity, quantity, unit price, total price, + fees, inputs, and outputs. 3. Treat every wallet prompt as the final authorization boundary. 4. Do not continue when Core reports stale, incomplete, conflicting, or unavailable authority data. diff --git a/src/content/docs/reference/changelog.mdx b/src/content/docs/reference/changelog.mdx index c8ca499..be36c11 100644 --- a/src/content/docs/reference/changelog.mdx +++ b/src/content/docs/reference/changelog.mdx @@ -23,6 +23,39 @@ from, reported by [`GET /health`](/docs-core/api/health/) and by the ## Documentation +### 2026-09-24 + +- **Updated:** [Atomicals](/docs-core/markets/atomicals/) explains that prices + are per unit, that the fee is charged to both sides, the price and funding + refusals, how a timed-out final step is completed once, and why a legacy + ARC-20 lot spent elsewhere closes. +- **Updated:** [Atomicals](/docs-core/markets/atomicals/) names the refusals + a retry cannot fix (a wallet that does not hold the asset, a listed asset that + has moved, funding committed elsewhere) and says a listing leaves the book as + soon as its output is spent. +- **Updated:** [Atomicals Studio](/docs-core/create/atomicals-studio/) adds the + reveal window: 3 blocks for a Realm or Subrealm, 100 for an NFT. +- **Updated:** [Atomicals Studio](/docs-core/create/atomicals-studio/) adds + Manage > Separate for NFTs that share one output (as a direct Subrealm claim + leaves the parent and child), the early reveal for Realm and direct Subrealm + claims, and how a wallet short of funding is reported. +- **Updated:** [Marketplace v1 gates](/docs-core/markets/marketplace-v1/) and + [Market and reader states](/docs-core/troubleshooting/states/) say that + prices are per unit and that a check never applies an action twice. + +### 2026-09-23 + +- **New:** [Atomicals Studio](/docs-core/create/atomicals-studio/), covering + every creation tool, its address, and which wallet signs it. +- **Updated:** [Atomicals](/docs-core/markets/atomicals/) now lists each + market's address, every trading action, the asking-price floor, and how to + recover a request that timed out. +- **Updated:** [What Core is](/docs-core/start/what-core-is/) describes the + `/inscribe` page, which links to Studio and to Inscribe instead of + redirecting. +- **Updated:** [Market and reader states](/docs-core/troubleshooting/states/) + adds the unknown-outcome lock. + ### 2026-09-01 Rebuilt as a documentation site rather than a folder of Markdown guides. diff --git a/src/content/docs/start/what-core-is.mdx b/src/content/docs/start/what-core-is.mdx index 9903488..1e2eb72 100644 --- a/src/content/docs/start/what-core-is.mdx +++ b/src/content/docs/start/what-core-is.mdx @@ -88,8 +88,11 @@ are **Wallet**, **Inscribe**, and **StampDEX**. Each protocol page on this site lists what the registry records for every surface, so a reader who cannot do something in Core can see whether another product can. -Inscribe is a hand-off rather than an embedded screen: opening Inscribe from -Core navigates to the Inscribe application rather than loading it inside Core. +Atomicals are created inside Core, in +[Atomicals Studio](/docs-core/create/atomicals-studio/). Other protocols are +inscribed in the separate Inscribe application. Core's `/inscribe` page links +to both, and Inscribe opens only when you follow its link: Core never +redirects you there on its own. ## Chains and networks diff --git a/src/content/docs/troubleshooting/states.mdx b/src/content/docs/troubleshooting/states.mdx index 876ef51..a68607f 100644 --- a/src/content/docs/troubleshooting/states.mdx +++ b/src/content/docs/troubleshooting/states.mdx @@ -32,6 +32,7 @@ import Provenance from '../../../components/Provenance.astro'; | **A column that is absent** | The source cannot answer that question at all | No | Not the same as a column of zeroes | | **A disabled control with a reason** | The protocol supports the action; a live gate disagrees | Yes, refreshing rechecks that exact route | An earlier ready result is never reused | | **No control at all** | The protocol does not support the action | No | The [support matrix](/docs-core/protocols/support-matrix/) gives the reason | +| **Earlier request outcome unknown** | A request timed out and may have applied. Other actions on that asset are locked | No. Select **Check what happened** instead | Checking asks the market under the original request key, so the action never applies twice. See [Atomicals](/docs-core/markets/atomicals/#when-a-request-times-out) | ## The distinction that matters most