Promote develop: Atomicals public release docs

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: [

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/)

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/)

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';
+
+<Provenance
+  repo="bitcoinuniverseio/core (private)"
+  source="frontend/src/pages/AtomicalsStudio/, frontend/src/services/atomicals-studio/"
+  chain="bitcoin"
+  network="mainnet"
+  verified="2026-09-23"
+/>
+
+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/<family>/<action>`, 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/)

src/content/docs/markets/atomicals.mdx

@@ -12,11 +12,11 @@ import Provenance from '../../../components/Provenance.astro';
 
 <Provenance
   repo="bitcoinuniverseio/core (private)"
-  source="backend/packages/ecosystem-contracts/lib/protocols.js, Atomicals execution service"
+  source="backend/packages/ecosystem-contracts/lib/protocols.js, Marketplace v1 action page, Atomicals execution service"
   chain="bitcoin"
   network="mainnet"
   lifecycle="enabled"
-  verified="2026-09-01"
+  verified="2026-09-23"
 />
 
 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,14 +150,19 @@ 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.
 
 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/)

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.

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.

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