From 1adc2ab0340eaebf4f84ac985fac24ba0c82c698 Mon Sep 17 00:00:00 2001
From: migberto <146127140+migberto@users.noreply.github.com>
Date: Thu, 17 Sep 2026 13:06:14 +0000
Subject: [PATCH] docs(wallet): explain exact total-price token lot approvals

---
 llms.txt                                      |   2 +-
 .../docs/assets/zcash-market-listings.mdx     | 126 ++++++++++--------
 2 files changed, 68 insertions(+), 60 deletions(-)

diff --git a/llms.txt b/llms.txt
index ef6f37d..048d156 100644
--- a/llms.txt
+++ b/llms.txt
@@ -67,7 +67,7 @@
 - [What this release authorizes](https://bitcoinuniverseio.github.io/docs-wallet/assets/support-state): The generated answer to which protocol operations Universe Wallet 1.7.5.8 authorizes, and why the number is what it is.
 - [What a digital artifact is](https://bitcoinuniverseio.github.io/docs-wallet/assets/what-a-digital-artifact-is): How an inscription, a token balance, and a rare satoshi actually exist on Bitcoin, and why that makes them fragile in an ordinary wallet.
 - [Why an action is unavailable](https://bitcoinuniverseio.github.io/docs-wallet/assets/why-unavailable): What the unavailable screen means, what it is not, and the list of things that will not change it.
-- [Zcash market listings](https://bitcoinuniverseio.github.io/docs-wallet/assets/zcash-market-listings): What a Zerdinal listing signature commits you to, why the approval can be blocked outright, and why cancelling a listing is only advisory.
+- [Zcash market listings](https://bitcoinuniverseio.github.io/docs-wallet/assets/zcash-market-listings): Review Zerdinal listings and full token lots with exact total prices, clear quantities, and a separate purchase approval.
 
 ## Safety
 
diff --git a/src/content/docs/assets/zcash-market-listings.mdx b/src/content/docs/assets/zcash-market-listings.mdx
index bc954f9..cd02a9b 100644
--- a/src/content/docs/assets/zcash-market-listings.mdx
+++ b/src/content/docs/assets/zcash-market-listings.mdx
@@ -1,88 +1,96 @@
 ---
 title: Zcash market listings
-description: What a Zerdinal listing signature commits you to, why the approval can be blocked outright, and why cancelling a listing is only advisory.
+description: Review Zerdinal listings and full token lots with exact total prices, clear quantities, and a separate purchase approval.
 sourceRepo: bitcoinuniverseio/wallet
-sourcePath: backend/shared/utils/zcash-tx.ts, frontend/ui/pages/Approval/components/ZcashSignMarketListing.tsx
+sourcePath: backend/shared/utils/zcash-market-settlement.ts, frontend/ui/pages/Approval/components/ZcashSignMarketSettlement/index.tsx
 chain: [zcash]
 lifecycle: not-released
-lastVerified: 2026-09-01
+lastVerified: 2026-09-17
 ---
 
 import { Aside } from '@astrojs/starlight/components';
-import snapshot from '../../../../capability-snapshot.json';
-
-Universe Wallet implements listing signatures for the Universe market's signed-order protocol, ZMarket
-Orders v1: a fixed-price offer to sell a Zerdinal inscription.
-
-<Aside type="danger" title="Not available in any released build">
-`market-list` sits on the Zerdinals intent list, and the release matrix authorizes it nowhere. In
-{snapshot.walletVersion} the authorized count is {snapshot.supportedProtocolCount} of{' '}
-{snapshot.protocolCount}. The build currently served by the Chrome Web Store is older still and
-predates Zcash support entirely, so it cannot sign a Zerdinal under any circumstance. Until a release
-carries the evidence, a listing request fails closed and names what is missing. See
-[Which version you are running](/docs-wallet/start/versions).
+
+Universe Wallet's source supports Zerdinal listings and full-lot purchases of ZRune and ZRC-20
+tokens. A full lot moves everything listed on one outpoint in one purchase. It does not split the
+lot into partial fills.
+
+<Aside type="caution" title="Check your installed build">
+This source update is not an extension release. Listing and purchase signing require the installed
+build to authorize the corresponding operation. Source tests alone do not make the controls
+available. If the wallet reports that an operation is unavailable, keep that restriction in place.
+See [Which version you are running](/docs-wallet/start/versions) and
+[What this release authorizes](/docs-wallet/assets/support-state).
 </Aside>
 
-## One signature, one exact outcome
+## What you are buying
+
+| Asset | What the lot represents |
+| --- | --- |
+| ZRune | The listed token balance carried by one outpoint |
+| ZRC-20 (zord) | One pending transfer inscription evaluated under zord rules |
+| ZRC-20 (zecscriptions) | One pending transfer inscription evaluated under zecscriptions rules |
+
+The two ZRC-20 rulesets have separate identities and balances. A matching ticker does not make them
+interchangeable. The purchase approval names the selected ruleset.
 
-A listing is a single signature under `SIGHASH_SINGLE | ANYONECANPAY` over a Zcash transaction digest
-computed from the listing terms alone. It binds your asset outpoint to exactly one outcome: any
-transaction that spends that outpoint must pay your own address the exact listed price. Everything
-else about the final settlement is the buyer's to build, and your signature deliberately does not
-constrain it.
+## Read the quantity and total together
 
-There is no escrow and no service custody. The market cannot move your asset, and equally your
-signature cannot choose the buyer: anyone holding it can settle the offer by paying you.
+The approval shows **Full lot** in base units and **Total lot price** in ZEC or testnet ZEC.
+Base units are the token's smallest units, not necessarily whole tokens. For a token with 18 decimal
+places, `100000000000000000000` base units represent 100 tokens. Confirm the token's decimal places
+and lot on the market before approving.
 
-## What the wallet checks before showing the approval
+New total-price lots can have a price smaller than one zatoshi per base unit. The wallet shows their
+exact total without inventing a rounded unit price. Existing per-unit listings retain their exact
+price per base unit and also show the derived total.
 
-- The request contains exactly the listing terms and optional asset evidence. Any other field is
-  rejected before anything is reviewed.
-- The seller address is the connected account's own Zcash address, and the payout script pays that
-  same address, so the wallet never authorizes a sale of someone else's asset or a payout to anyone
-  else.
-- The network in the terms matches the active wallet chain.
-- The pinned consensus branch matches the network's next block, so the listing becomes invalid by
-  construction across a network upgrade.
-- The price is above the relayable floor, and the platform fee amount and fee script are consistent
-  with each other.
+Review **Buyer debit**, the seller proceeds, creator payout, platform fee, network fee, change, and
+maximum debit. Check the delivery address separately from the address receiving your change.
+A signature does not mean the asset has arrived: delivery remains pending until the transaction is
+confirmed and indexed.
 
-## Why the approval can be blocked
+## What a listing signature allows
 
-The signature sells everything the listed outpoint carries, so the wallet requires an asset verdict
-for that outpoint before it lets you approve.
+A listing signature commits one asset outpoint to an exact seller payout. The payout must return
+to your connected wallet address. Anyone holding the signature can settle a conforming purchase;
+it does not reserve the offer for a particular buyer.
 
-- An outpoint with **no asset verdict** blocks the approval, because what the signature would sell
-  cannot be shown.
-- A verdict that **does not carry the listed asset** blocks the approval and names the mismatch.
-- An outpoint carrying **more than the listed asset** is shown in full, because a sale delivers all of
-  it together.
+There is no escrow or service custody. Review the exact amount you will receive, the listed
+outpoint and everything it carries, its expiry, and the selected network before signing.
 
-Blocked is not a warning you can click through. The approve control stays disabled and the screen
-states the reason in the same words the wallet enforces.
+## Why an approval can be blocked
 
-## The three consequences of approving
+The wallet refuses an unverifiable asset outpoint, a mismatched account or network, a changed
+consensus branch, invalid transaction bytes, or a buyer debit above the approved maximum.
+A token purchase must settle the full lot from one outpoint. Partial fills and additional lot
+outpoints are refused.
 
-1. **A listing is a public offer.** Anyone can settle it at exactly these terms.
-2. **Cancellation is advisory.** Cancelling removes the listing from the market. The signature stays
-   valid until the asset moves or the expiry block passes. The only certain revocation is transferring
-   the asset to yourself.
-3. **The ZEC riding on the asset outpoint transfers to the buyer with the asset.** Set the price with
-   that in mind.
+The wallet verifies its own funding and checks asset claims from Universe-operated services.
+The market and indexer establish the token quantity and ruleset. Missing or conflicting evidence
+must be resolved before approval; a disabled approve control is not a warning to click through.
 
-The screen also shows the exact amount you are paid, the platform fee, which the buyer pays, the block
-at which the offer dies, the consensus branch, the outpoint being committed, and the digest the
-signature is over.
+## Cancellation and expiry
+
+1. **A listing is public.** Anyone can settle it while its signature remains valid.
+2. **Cancellation removes the market offer.** It does not revoke a signature already supplied.
+   A confirmed spend of the listed outpoint invalidates that offer. A positive expiry also limits
+   the signature; an offer marked **No expiry** has no expiry block.
+3. **The ZEC riding on the asset outpoint transfers with it.** Consider that value when setting
+   your selling price.
+
+Disconnecting a site does not revoke a previously issued listing signature.
 
 ## After you approve
 
-Approval alone signs nothing. The wallet re-reviews the exact terms after your approval and before any
-key material is touched, and checks the consensus branch against the network again. If the terms no
-longer match what you saw, or the asset can no longer be verified, the wallet refuses instead of
-signing.
+The wallet checks the request again before signing. Changes to the account, network, site,
+reviewed order, transaction, or maximum debit require a fresh approval. Purchase signing touches
+only the reviewed buyer inputs and preserves the seller's authorization and transaction outputs.
+
+If a submitted purchase has an unknown outcome, retain its execution identity and check its
+recorded status before retrying. Do not assume an interrupted page means the transaction failed.
 
 ## Related
 
 - [What a signature authorizes](/docs-wallet/concepts/what-a-signature-authorizes)
-- [Review a PSBT](/docs-wallet/tasks/review-a-psbt)
+- [Connection permissions](/docs-wallet/concepts/connections)
 - [What this release authorizes](/docs-wallet/assets/support-state)