docs(contracts-sui): add dApp 1 — Sui Marketplace Reference walkthrough#152
Open
stevep0z wants to merge 4 commits intoOpenZeppelin:mainfrom
Open
docs(contracts-sui): add dApp 1 — Sui Marketplace Reference walkthrough#152stevep0z wants to merge 4 commits intoOpenZeppelin:mainfrom
stevep0z wants to merge 4 commits intoOpenZeppelin:mainfrom
Conversation
New page under contracts-sui/1.x/learn that introduces the Sui Marketplace reference build (https://github.com/OpenZeppelin/openzeppelin-sui-marketplace). The page is an overview-level companion to the in-repo walkthrough; it points readers to the repo + README, the in-repo docs/ folder, and the companion video walkthrough as three educational assets, then walks through architecture, object model, and purchase flow with embedded diagrams. Sections: - Educational assets — repo, in-repo docs/, video - Video walkthrough — Callout placeholder + iframe ready-to-uncomment with TBD_VIDEO_ID once the video is published - Architecture — Frame 1 diagram + 3-layer workspace prose - Object model — Frame 2 diagram + Shop / ShopOwnerCap / ShopItem<phantom T> / PriceInfoObject prose - Purchase flow — Frame 3 diagram + PTB atomicity narrative including conservative mantissa, dual-bound guardrails, and openzeppelin_math mul_div usage - Quickstart — points to the repo's README - Key code paths — table mapping each pattern to file + line range - New to Move and Sui? — concept links + broader Move/Sui references - Related OpenZeppelin packages — math + access (future migration) - Where to go next — CTAs Diagrams referenced from the page expect three PNGs at public/contracts-sui/dapp-1-marketplace/ — frame-1-architecture.png, frame-2-object-model.png, frame-3-purchase-ptb.png. These are exported from the project's Figma file and will be added in a follow-up commit on this branch before merge. Navigation: - src/navigation/sui/current.json: adds the page under the Learn folder after Math and Access walkthroughs. - content/contracts-sui/1.x/learn/index.mdx: restructures the Learn index into "Package walkthroughs" and "dApp examples" sections so future dApp pages have an obvious home.
Three diagrams referenced by content/contracts-sui/1.x/learn/dapp-1-marketplace.mdx: - frame-1-architecture.png — repository and module structure - frame-2-object-model.png — object model and ownership - frame-3-purchase-ptb.png — buyer purchase PTB (atomic) Exported from the project's Figma file at 3840x2160 (2x for Retina) so they remain crisp when displayed full-width on the docs site.
✅ Deploy Preview for openzeppelin-docs-v2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Netlify preview build failed with `Expected a closing tag for <phantom>`
on /contracts-sui/1.x/learn/dapp-1-marketplace. Two image alt-text
strings contained raw angle-bracket generics (`ShopItem<phantom T>`,
`ShopItem<Bike>`, `Coin<USDC>`) that the MDX parser interpreted as
unclosed JSX tags.
Backticks elsewhere in the body protect inline code spans from JSX
parsing, but image alt text is parsed as JSX-eligible markup. Rewrote
the affected alt strings to describe the receipts in prose without
angle brackets:
- Frame 2 alt: "Buyers receive an owned phantom-typed ShopItem receipt."
- Frame 3 alt: "transfer of the bike receipt to the buyer (step 2),
and transfer of the USDC change to the buyer (step 3)."
No body-prose changes; the technical narrative still uses backtick-wrapped
generics where appropriate.
stevep0z
force-pushed
the
docs/sui-marketplace-dapp-1
branch
from
a2d9cb6 to
b2a001a
Compare
ernestognw
reviewed
May 6, 2026
Comment on lines
+80
to
+87
| | One-time witness + `init` | [`shop.move`](https://github.com/OpenZeppelin/openzeppelin-sui-marketplace/blob/main/packages/dapp/contracts/oracle-market/sources/shop.move) (lines ~106–111) | Publish-time `Publisher` claim | | ||
| | Capability pattern | [`shop.move`](https://github.com/OpenZeppelin/openzeppelin-sui-marketplace/blob/main/packages/dapp/contracts/oracle-market/sources/shop.move) (lines ~117–122) | `ShopOwnerCap` struct, `shop_id` binding | | ||
| | Shared `Shop` with typed Tables | [`shop.move`](https://github.com/OpenZeppelin/openzeppelin-sui-marketplace/blob/main/packages/dapp/contracts/oracle-market/sources/shop.move) (lines ~125–140) | `accepted_currencies` keyed by `TypeName` | | ||
| | Phantom-typed receipt | [`listing.move`](https://github.com/OpenZeppelin/openzeppelin-sui-marketplace/blob/main/packages/dapp/contracts/oracle-market/sources/listing.move) (lines ~46–59) | `ShopItem<phantom T>` with `key, store` and no `drop` | | ||
| | Oracle identity assertion | [`shop.move`](https://github.com/OpenZeppelin/openzeppelin-sui-marketplace/blob/main/packages/dapp/contracts/oracle-market/sources/shop.move) (lines ~815–830) | `assert_price_info_identity!` macro | | ||
| | Conservative price mantissa | [`currency.move`](https://github.com/OpenZeppelin/openzeppelin-sui-marketplace/blob/main/packages/dapp/contracts/oracle-market/sources/currency.move) (lines ~259–269) | Lower-bound settlement | | ||
| | `openzeppelin_math::mul_div` usage | [`currency.move`](https://github.com/OpenZeppelin/openzeppelin-sui-marketplace/blob/main/packages/dapp/contracts/oracle-market/sources/currency.move) (lines ~230–235) | Explicit rounding + overflow abort | | ||
| | PTB construction | [`buy.ts`](https://github.com/OpenZeppelin/openzeppelin-sui-marketplace/blob/main/packages/domain/core/src/flows/buy.ts) | `maybeUpdatePythPriceFeed` + `buildBuyTransaction` | |
Member
There was a problem hiding this comment.
Is it okay pointing to main rather than a specific commit? This files will update and the references may break
|
|
||
| ## Video walkthrough | ||
|
|
||
| <iframe width="100%" height="450" src="https://www.youtube.com/embed/n53w3IGLnf8" title="Sui Marketplace Fullstack Example: Move, Pyth, and OpenZeppelin Math Libraries" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe> |
Member
There was a problem hiding this comment.
Nit: in JSX/MDX these attributes should be camelCase — frameBorder and allowFullScreen. The lowercase HTML form will likely emit a console warning during pnpm run build.
|
|
||
| The settlement math itself defends against oracle uncertainty: the contract uses Pyth's lower bound (`mantissa - confidence`, the `mu - sigma` of the reported price), aborts when the confidence interval is too wide relative to the price, and applies dual-bound guardrails on freshness and confidence (sellers set caps; buyers can tighten via overrides but never loosen). The final price-to-coin conversion uses [`openzeppelin_math::u128::mul_div`](/contracts-sui/1.x/math) with explicit `rounding::up()` — overflow surfaces as an explicit transaction abort rather than silent corruption. | ||
|
|
||
| The PTB structure is what makes this safe. There is no transaction order in which `buy_item` runs against a stale feed, because step 0 is unconditionally the prior call in the same atomic block. |
Member
There was a problem hiding this comment.
Nit: prior call reads slightly awkward here — preceding call flows better. Non-blocking.
|
|
||
| ## Architecture | ||
|
|
||
|  |
Member
There was a problem hiding this comment.
Three 3840×2160 PNGs in public/ add up — fine for Retina, but worth confirming total page weight is acceptable, or considering WebP. Non-blocking.
|
|
||
| A fullstack reference build of an on-chain marketplace on Sui. Items are priced in USD cents and settled in any oracle-registered currency via [Pyth](https://pyth.network/), with safe arithmetic at the contract layer handled by [`openzeppelin_math`](/contracts-sui/1.x/math). The repo demonstrates how Sui's object model, capability pattern, phantom types, and Programmable Transaction Blocks compose into production-shaped application code. | ||
|
|
||
| ## Educational assets |
Member
There was a problem hiding this comment.
Forward-looking note: no explicit anchor IDs on the section headings here. If this page grows and we want to deep-link from the intro (like access-walkthrough.mdx does), the convention per docs/CLAUDE.md is <a id="anchor-name"></a> HTML tags, not {#anchor} syntax. Not needed at the current length — flagging for future edits.
ernestognw
approved these changes
May 6, 2026
Member
ernestognw
left a comment
ernestognw
left a comment
There was a problem hiding this comment.
LGTM with some non-blocking comments. Thanks @stevep0z
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
2 participants
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.
Documentation Pull Request
Summary
Adds a new overview page to the contracts-sui Learn section for the Sui Marketplace reference build (https://github.com/OpenZeppelin/openzeppelin-sui-marketplace). The page introduces three educational assets (repo + README, in-repo `docs/` folder, video walkthrough), embeds three architecture diagrams, and signposts to the in-repo walkthrough for depth rather than duplicating it.
Type of Change
Related Issues
No related issue.
What's in this PR
New page: `content/contracts-sui/1.x/learn/dapp-1-marketplace.mdx`
Sections: Educational assets · Video walkthrough (placeholder + ready-to-uncomment iframe) · Architecture · Object model · Purchase flow · Quickstart · Key code paths · New to Move and Sui? · Related OpenZeppelin packages · Where to go next.
Diagrams: Three PNGs at `public/contracts-sui/dapp-1-marketplace/` (3840×2160, exported from Figma at 2x for Retina).
Navigation:
Video embed: A `` placeholder is in place; the iframe sits in a JSX comment block (`{/* ... */}`) below it, ready to uncomment with a single grep on `TBD_VIDEO_ID` once the YouTube video is published. No broken player renders in the meantime.
Companion PR
Improvements to the marketplace repo's README and in-repo docs (which this page links to throughout) are in a companion PR at OpenZeppelin/openzeppelin-sui-marketplace.
Checklist
Additional Notes
The video referenced on this page (~18 min) hasn't been published yet. The placeholder + commented iframe are designed so the page is useful immediately, and the video swap is a one-line edit when ready.