From f9dd2b1e12507ee0ba5861ca616fbfe3fadd098d Mon Sep 17 00:00:00 2001 From: Zihe Huang Date: Tue, 27 Feb 2024 01:06:26 +0800 Subject: [PATCH] [docs] Fix broken link for shared/owned objects and add diagrams part 2 (#16386) ## Description Update code sample with perma link and add diagrams to improve readability of Shared/owned objects concept ## Test Plan Visual Inspection --- If your changes are not user-facing and do not break anything, you can skip the following section. Otherwise, please briefly describe what has changed under the Release Notes section. ### Type of Change (Check all that apply) - [ ] protocol change - [ ] user-visible impact - [ ] breaking change for a client SDKs - [ ] breaking change for FNs (FN binary must upgrade) - [ ] breaking change for validators or node operators (must upgrade binaries) - [ ] breaking change for on-chain data layout - [ ] necessitate either a data wipe or data migration ### Release notes --------- Co-authored-by: ronny-mysten <118224482+ronny-mysten@users.noreply.github.com> --- .../guides/developer/sui-101/shared-owned.mdx | 48 +++++++++++++++++-- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/docs/content/guides/developer/sui-101/shared-owned.mdx b/docs/content/guides/developer/sui-101/shared-owned.mdx index 9f7d77fe9578a..db643e70642d6 100644 --- a/docs/content/guides/developer/sui-101/shared-owned.mdx +++ b/docs/content/guides/developer/sui-101/shared-owned.mdx @@ -179,9 +179,35 @@ The `swap` function checks that senders and recipients match and that each party ### Shared objects -[Code Sample](https://github.com/MystenLabs/sui/blob/main/examples/move/escrow/sources/shared.move) +[Code Sample](https://github.com/MystenLabs/sui/blob/93e6b4845a481300ed4a56ab4ac61c5ccb6aa008/examples/move/escrow/sources/shared.move) -The protocol in the shared object case is less symmetric, but still starts with the first party locking the object they wish to swap. The second party can then view the object that was locked, and if they decide they want to swap with it, they indicate their interest by creating a swap request: +The protocol in the shared object case is less symmetric, but still starts with the first party locking the object they want to swap. +```mermaid +flowchart TB + B["Locked<fa:fa-coins B>, fa:fa-key key_b"] + + subgraph Buyer + direction TB + a1(fa:fa-coins B)--escrow::lock-->B + end +``` + +The second party can then view the object that was locked, and if they decide they want to swap with it, they indicate their interest by creating a swap request: + +```mermaid +flowchart TB + S["fa:fa-wrench S, + exchange_key: fa:fa-key key_b, + recipient: Buyer + "] + + id1(Shared Object)-->id2(Escrow<fa:fa-wrench S>) + + subgraph Seller + direction TB + S--create-->id2 + end +``` ```move public fun create( @@ -202,7 +228,21 @@ public fun create( } ``` -This time the swap request is a shared object, and accepts the object being escrowed directly (not locked). The request remembers the address that sent it (who is allowed to reclaim the object if the swap hasn't already happened), and the intended recipient, who is then expected to continue the swap by providing the object they initially locked: +This time the `create` request accepts the object being escrowed directly (not locked), and creates a shared `Escrow` object. The request remembers the address that sent it (who is allowed to reclaim the object if the swap hasn't already happened), and the intended recipient, who is then expected to continue the swap by providing the object they initially locked: + +```mermaid +flowchart TB + + subgraph Buyer + direction TB + id1(Escrow<fa:fa-wrench S>,\n fa:fa-key key_b,\n Locked<fa:fa-coins B>) + id2(fa:fa-wrench S) + id1-->swap-->id2 + end + + swap--fa:fa-coins B-->Seller +``` + ```move public fun swap( @@ -230,7 +270,7 @@ public fun swap( } ``` -Even though the `Escrow` request is a shared object that is accessible by anyone, the Move interface ensures that only the original sender and the intended recipient can successfully interact with it. `swap` checks that the locked object matches the object that was requested when the `Escrow` was created (again, by comparing key IDs) and assumes that the intended recipient wants the escrowed object (if they did not, they would not have called `swap`). +Even though the `Escrow` object is a shared object that is accessible by anyone, the Move interface ensures that only the original sender and the intended recipient can successfully interact with it. `swap` checks that the locked object matches the object that was requested when the `Escrow` was created (again, by comparing key IDs) and assumes that the intended recipient wants the escrowed object (if they did not, they would not have called `swap`). Assuming all checks pass, the object held in `Escrow` is extracted, its wrapper is deleted and it is returned to the first party. The locked object offered by the first party is also unlocked and sent to the second party, completing the swap.