Merge pull request #47 from nervina-labs/develop

Update cota overview examples
nervina-labs · Jun 14, 2022 · 7e549c8 · 7e549c8
2 parents c7afb67 + c2eb3a4
commit 7e549c8
Showing 1 changed file with 64 additions and 32 deletions.
diff --git a/docs/cota/overview.md b/docs/cota/overview.md
@@ -22,43 +22,75 @@ The CoTA SMT includes four kinds of leaves: define, hold, withdraw and claim.
 
 When we say you own an NFT, it means either your hold leaves contain the NFT, or a sender's withdrawal leaf has your address as the destination address and you have not claimed the NFT to your SMT.
 
-As an issuer, Alice can define an NFT collection and then mint NFTs to others. As a receiver, Bob can get the NFTs from Alice and claim the NFTs to his own SMT and withdraw to others after claiming.
+As an issuer, Alice can define an NFT collection and then mint NFTs to others. As a receiver, Bob can get the NFTs from Alice and claim the NFTs to his own SMT and withdraw to Tom after claiming. Now Tom owns the NFTs from Bob, but his SMT doesn't have the NFTs before claiming.
 
-## CoTA NFT Flow
+## Quick Start
+
+You can use [cota-sdk](./sdk.md) to register, define, mint, claim, withdraw and transfer and examples have been provided in SDK.
 
+### Register to Create CoTA Cell
+
+You know, everyone must register only one cota cell before starting cota-related operations. You can register cota cell with the [registry example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/registry.ts). When the registry transaction is in the blockchain, your lock hash will be a leaf of the global registry SMT and you will have a cota cell with your own lock script that means just only you can spend the cota cell to complete minting or transferring operations.
+
+```
+ckb address <==> lock script ==> lock hash
 ```
-                        Register CoTA cells firstly
-1. Alice & Bob & Tom ----------------------------------> Alice CoTA cell & Bob CoTA cell & Tom CoTA cell
-
-            Define CoTA NFT                             Mint CoTA NFT A1 to receivers
-2. Alice -----------------------> NFT collection A -----------------------------------> Receivers (Bob)
-
-                    Claim NFT A1                                  Withdraw NFT A1 to Tom
-       Action1 |-------------------------> Bob hold NFT A1 now ----------------------------------> Bob doesn't hold NFT A1 now
-      |
-      |             Transfer NFT A1 to Tom
-3. Bob Action2 |-----------------------------------> Bob doesn't hold NFT A1 now
-      |
-      |         Claim and Update NFT A1 information
-       Action3 |-----------------------------------> Bob hold CoTA NFT A1 with new information
-
-                    Claim NFT A1                                 Withdraw NFT A1 to other receivers
-        Action1 |-------------------------> Tom hold NFT A1 now ----------------------------------> Tom doesn't hold NFT A1 now
-       |
-4. Tom |
-       |          Transfer NFT A1 to other receivers
-        Action2 |-----------------------------------> Tom doesn't hold NFT A1 now
 
+The ckb address, lock script and lock hash all can be as account address for someone who owns the private key and using lock hash as leaf node of the global registry SMT is to reduce complexity.
+
+### To be an Issuer
+
+If you are an issuer who want to mint NFTs to others, you can create issuer information to the blockchain with the [issuer example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/issuer.ts). You can type issuer information with [IssuerInfo](https://github.com/nervina-labs/cota-sdk-js/blob/develop/src/types/service.ts#L14) data type who defines the issuer detail fields. The issuer information will be saved into Witnesses of the ckb transaction in the blockchain to reduce capacity usage and can be read from the blockchain by anyone.
+
+```TypeScript
+interface IssuerInfo {
+  name: string
+  description?: string
+  avatar?: string
+}
 ```
 
-- **Registry:** Every address should be registered firstly
-- **Define:** The issuer can define a collection NFTs with total/name/description/image etc.
-- **Mint:** The issuer mint the defined NFTs to the receivers (withdraw to the receivers actually)
-- **Claim:** The receiver can claim the NFT from the mint, and now the receiver hold the NFT
-- **Update:** The holder of the NFT(the NFT must be claimed) can update the information (characteristic/state etc.)
-- **Withdraw:** The holder of the NFT can withdraw the NFT to any other CKB address
-- **Transfer:** To simplify, transfer combines the claim and withdrawal into one operation. The receiver can claim the NFT from the mint and withdraw the same NFT to others in a transaction.
+### Define an NFT Collection
+
+As an issuer, you can define an NFT collection with the [define example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/define.ts) and you can type the NFT collection information with [CotaInfo](https://github.com/nervina-labs/cota-sdk-js/blob/develop/src/types/service.ts#L20) data type who defines the collection detail fields. You will get the unique `cota_id` from the define transaction and all the NFTs of the collection will share the same collection information and the `cota_id`.
+
+```TypeScript
+interface CotaInfo {
+  name: string
+  image: string
+  description?: string
+  audio?: string
+  video?: string
+  model?: string
+  characteristic?: [string, number][]
+  properties?: string
+}
+```
 
-## Quick Start
+### Mint NFTs
 
-You can use [cota-sdk](./sdk.md) to register, define, mint, claim, withdraw and transfer and examples have been provided in SDK.
+After defining an NFT collection, you can mint NFTs to others with the [mint example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/mint.ts). All the minted NFTs will share the same collection information and `cota_id`, type are distinguished by different token indexes. And you can also set different values of NFT fields(state and characteristic) to implement different properties for every NFT.
+
+### Claim NFTs
+
+If you have NFTs minted by an issuer, you can claim NFTs with the [claim example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/claim.ts). Claiming means adding the NFTs to your own SMT and you can update the NFTs information or withdraw to others after claiming.
+
+### Update NFTs information
+
+You can update the NFTs information(state and characteristic) with the [update example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/update.ts) after claiming.
+
+### Claim and Update NFTs
+
+You can claim NFTs and update the NFTs information(state and characteristic) in one operation with the [claim-update example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/claim-update.ts).
+
+### Withdraw NFTs
+
+You can withdraw NFTs to others with the [withdraw example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/withdraw.ts). Withdrawal means losing the ownership of the NFTs and the receiver can claim the NFTs at any time.
+
+### Transfer NFTs
+
+If you want to withdraw the NFTs to others before claiming, you can implement the operation with [transfer example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/transfer.ts). The transfer melts the claim and withdrawal into one operation to make the transfer more simple.
+
+### Transfer and Update NFTs
+
+You can claim NFTs, update the NFTs information(state and characteristic) and withdraw the NFTs to others in one operation with the [transfer-update example](https://github.com/nervina-labs/cota-sdk-js/blob/develop/example/transfer-update.ts).