From 1d9772825b1f5f1ebe725724bf39527d515b650b Mon Sep 17 00:00:00 2001 From: Alive24 Date: Mon, 20 Jan 2025 10:23:47 +0000 Subject: [PATCH 1/4] doc: Update on UDT README (Links should be updated) --- packages/udt/README.md | 153 +++++++++++++++++++++++++++++++---------- 1 file changed, 115 insertions(+), 38 deletions(-) diff --git a/packages/udt/README.md b/packages/udt/README.md index 992f8fb7..5f44d16e 100644 --- a/packages/udt/README.md +++ b/packages/udt/README.md @@ -36,66 +36,143 @@ Fully enabling CKB's Turing completeness and cryptographic freedom power.

+## Note + +- Try interactive demo at [CCC App - UDT](https://ccc-git-udtssridemo-aaaaaaaalive24.vercel.app?_vercel_share=zQkvWcsB2U9HRbpRFtF9w3xQT9msZDWb) +- Currently `ExecutorJsonRpc` is the only supported `Executor`. There will be more in the future and legacy support for `xUDT` will be added through `ckb-asset-indexer`. +> Note: A public SSRI Executor JSON RPC Point is being scheduled, and efforts are being made to make to provide in-browser SSRI execution with WASM. + +- At the moment, `UDT` and `UDTPausable` from `@ckb-ccc/udt` are fully supported with SSRI by extending the `ssri.Trait` class in `@ckb-ccc/ssri`. While you can build your own SSRI-based SDK for your SSRI-compliant script in reference to `@ckb-ccc/udt`, in the future, there will be built in TypeScript generation directly based on the Rust source code on compilation. + ## Quick Start -- At the moment, `UDT` and `UDTPausable` from `@ckb-ccc/udt` are fully supported through SSRI. In the future, there will be built in TypeScript generation directly based on the Rust source code on compilation. -- To instantiate a `UDT` script compliant with SSRI, you can provide the SSRI server url and also specify the OutPoint of the script code. -- You can also instantiate a `UDTPausable` script or other scripts that extends from `UDT`. +1. Create or setup your project with CCC (see guide [here](https://docs.ckbccc.com/index.html#md:quick-start-with-create-ccc-app-recommended)) +2. Start up your local SSRI server through docker: + +```shell +docker run -p 9090:9090 hanssen0/ckb-ssri-server +``` + +3. Prepare the `OutPoint` of your SSRI-compliant UDT script. It's recommended to deploy your UDT script with Type ID, and the following way would allow you to get the `OutPoint` programmatically even if the script gets upgraded: ```ts -import { Server } from "@ckb-ccc/ssri"; -import { Udt, UdtPausable } from "@ckb-ccc/udt"; +import { ccc } from "@ckb-ccc/ccc"; +import { signer } from "@ckb-ccc/playground"; + +const udtScriptCell = await signer.client.findSingletonCellByType({ + codeHash: + "0x00000000000000000000000000000000000000000000000000545950455f4944", + hashType: "type", + args: "0xf0bad0541211603bf14946e09ceac920dd7ed4f862f0ffd53d0d477d6e1d0f0b", +}); +if (!scriptCell) { + throw new Error("UDT script cell not found"); +} +``` -const { signer } = useApp(); -const server = new Server("https://localhost:9090"); +4. Prepare the Type script object of your UDT. You can provide the code hash yourself by copying from the explorer, or get it programmatically from the `OutPoint` of your UDT script. -const udt = new Udt( - server, - { - txHash: "0x...", - index: 0, - }, - { - codeHash: "0x...", - hashType: "type", - args: "0x...", - }, -); +```ts +const udtCodeHash = udtScriptCell.cellOutput.type?.hash(); +if (!udtCodeHash) { + throw new Error("UDT code hash not found"); +} +const udtType = { + codeHash: udtCodeHash, + hashType: "type", + args: "0x02c93173368ec56f72ec023f63148461b80e7698eddd62cbd9dbe31a13f2b330", +}; +``` -const udtPausable = new UdtPausable( - server, - { - txHash: "0x...", - index: 0, - }, +5. You have everything ready, now you can create an instance of your UDT and interact with it. + +```ts +const executor = new ccc.ssri.ExecutorJsonRpc("http://localhost:9090"); +const udt = new ccc.udt.Udt(udtScriptCell.outPoint, udtType, { + executor, +}); +``` + +You can directly call the methods in the script: + +```ts +const { res: udtSymbol } = await udt.symbol(); +``` + +The same script might have implemented multiple SSRI traits or sub-traits at the same time, but you can instantiate the same script arbitrarily with different traits as long as the script implemented the traits you want. + +```ts +const pudt = new ccc.udt.UdtPausable( + udtScriptCell.outPoint, + udtType, { - codeHash: "0x...", - hashType: "type", - args: "0x...", + executor, }, ); +const pudtEnumeratePaused = await pudt.enumeratePaused(); ``` -You can directly call the methods in the script: +## Advanced Usage + +1. Some of the methods allows you to generate a transaction object directly while taking care of most of the details for you. You just need to follow the guidance of the docs provided via your IDE. ```ts -const { res: udtSymbol } = await udt.symbol(); -const { res: pauseList } = await udtPausable.enumeratePaused(); +const receiverA = + "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq2jk6pyw9vlnfakx7vp4t5lxg0lzvvsp3c5adflu"; + +const { script: lockA } = await ccc.Address.fromString( + receiverA, + signer.client +); + +const udtTransferTx = ( + await udt.transfer(signer, [ + { + to: lockA, + amount: 10000, + }, + ]) +).res; ``` -Some of the methods can return a `ccc.Transaction`. For example, you can call `transfer` with the following params: +Many of these methods also allow you to pass in a previous `ccc.TransactionLike` object as the second argument, which allows you for example to transfer multiple UDT cells in a single transaction. ```ts -const { script: to } = await signer.getRecommendedAddressObj(); +const receiverB = + "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqflz4emgssc6nqj4yv3nfv2sca7g9dzhscgmg28x"; +const { script: lockB } = await ccc.Address.fromString( + receiverB, + signer.client +); +let combinedTransferTx = ( + await udt.transfer( + signer, + [ + { + to: lockB, + amount: 20000, + }, + ], + udtTransferTx + ) +).res; +``` + +2. You only need to complete the inputs of the transaction just like processing any other transactions with CCC. -const { res: transferTx } = await udt.transfer(signer, [{ to, amount: 100 }]); -const completedTx = await udt.completeUdtBy(transferTx, signer); +```ts +// Note: You need to connect your wallet for the following parts. You also need to have enough balance of the specified UDT in your wallet. +combinedTransferTx = await udt.completeBy(combinedTransferTx, signer); +await combinedTransferTx.completeFeeBy(signer); +await render(combinedTransferTx); +const combinedTransferTxHash = await signer.sendTransaction(combinedTransferTx); -await completedTx.completeInputsByCapacity(signer); -await completedTx.completeFeeBy(signer); -const transferTxHash = await signer.sendTransaction(completedTx); +console.log(combinedTransferTxHash); ``` +Full runnable example can be found at [here](https://live.ckbccc.com/?src=nostr:nevent1qqs8q20jvxqfsrhqw4te248qduex39dgls7qajhuc42kale0yqatdhspzemhxue69uhhyetvv9ujumn0wd68ytnzv9hxgqg5waehxw309ahx7um5wghx77r5wghxgetkqy28wumn8ghj7un9d3shjtnyv9kh2uewd9hspusjlf) + +

Read more about CCC on our website or GitHub Repo.

From 4a46bbd9732d0282a8b161ca5d05ea876f0e19da Mon Sep 17 00:00:00 2001 From: Alive24 Date: Mon, 20 Jan 2025 13:36:02 +0000 Subject: [PATCH 2/4] doc: README update --- packages/ssri/README.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/packages/ssri/README.md b/packages/ssri/README.md index a74280be..fa388cbb 100644 --- a/packages/ssri/README.md +++ b/packages/ssri/README.md @@ -36,18 +36,24 @@ Fully enabling CKB's Turing completeness and cryptographic freedom power.

-### Script-Sourced Rich Information +## Script-Sourced Rich Information -Read more about SSRI on [[EN/CN] Script-Sourced Rich Information - 来源于 Script 的富信息](https://talk.nervos.org/t/en-cn-script-sourced-rich-information-script/8256). +- Try interactive demo at [CCC App - SSRI](https://ccc-git-udtssridemo-aaaaaaaalive24.vercel.app?_vercel_share=zQkvWcsB2U9HRbpRFtF9w3xQT9msZDWb) +- Read more about SSRI on [[EN/CN] Script-Sourced Rich Information - 来源于 Script 的富信息](https://talk.nervos.org/t/en-cn-script-sourced-rich-information-script/8256). -NOTE: This is the base package for interaction with SSRI-Compliant scripts. +>## NOTE: This is the base package for interaction with SSRI-Compliant scripts +> +>If you are looking for UDT support, please refer directly to [@ckb-ccc/udt](https://www.npmjs.com/package/@ckb-ccc/udt) which supports both SSRI-compliant UDT and legacy support for `xUDT` through `ckb-asset-indexer` (coming soon). -If you are looking for UDT support, please refer directly to [@ckb-ccc/udt](https://www.npmjs.com/package/@ckb-ccc/udt) which supports both SSRI-compliant UDT and falling back to xUDT. +## Additional Note -### Related Projects +- Currently `ExecutorJsonRpc` is the only supported `Executor`. There will be more in the future and legacy support for `xUDT` will be added through `ckb-asset-indexer`. +- A public SSRI Executor JSON RPC Point is being scheduled, and efforts are being made to make to provide in-browser SSRI execution with WASM. -- [`ssri-server`](https://github.com/ckb-devrel/ssri-server): Server for calling SSRI methods. -- [`ckb_ssri_sdk`](https://github.com/ckb-devrel/ckb_ssri_sdk): A toolkit to help developers build SSRI-Compliant scripts on CKB with production level example script `pausable-udt` for reference. +## Related Projects + +- [`ssri-server`](https://github.com/ckb-devrel/ssri-server): `ExecutorJSONRpc` server for calling SSRI methods. +- [`ckb-ssri-std`](https://github.com/ckb-devrel/ckb-ssri-std): A toolkit to help developers build SSRI-Compliant scripts on CKB.

Read more about CCC on our website or GitHub Repo. From 1f7cb96374919e8af74abd1158bc4530b45b10f5 Mon Sep 17 00:00:00 2001 From: Alive24 Date: Thu, 23 Jan 2025 15:00:52 +0000 Subject: [PATCH 3/4] doc: additional guides and updated README update --- README.md | 10 +++ guides/quickstart_udt.md | 131 +++++++++++++++++++++++++++++++++++++++ packages/udt/README.md | 2 +- 3 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 guides/quickstart_udt.md diff --git a/README.md b/README.md index 0b5132b2..6fbec91c 100644 --- a/README.md +++ b/README.md @@ -110,6 +110,10 @@ We have done everything! - [Transfer native CKB token.](https://live.ckbccc.com/?src=https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/master/packages/examples/src/transfer.ts) - [Transfer all native CKB token.](https://live.ckbccc.com/?src=https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/master/packages/examples/src/transferAll.ts) - [Transfer UDT token.](https://live.ckbccc.com/?src=https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/master/packages/examples/src/transferUdt.ts) +- [Interact with UDT through @ckb-ccc/udt](https://live.ckbccc.com/?src=https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/master/packages/examples/src/udt/quickstart.ts): +- [Get UDT symbol through @ckb-ccc/udt.](https://live.ckbccc.com/?src=https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/master/packages/examples/src/udt/symbol.ts) +- [Check if a lock hash has been paused through @ckb-ccc/udt.](https://live.ckbccc.com/?src=https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/master/packages/examples/src/pausableUdt/isPaused.ts) +- [Transfer UDT token through @ckb-ccc/udt.](https://live.ckbccc.com/?src=https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/master/packages/examples/src/udt/transfer.ts) ## Quick Start with `create-ccc-app` (Recommended) @@ -221,6 +225,12 @@ import { generateDefaultScriptInfos } from "@ckb-ccc/lumos-patches"; registerCustomLockScriptInfos(generateDefaultScriptInfos()); ``` +## Additional Guides + +### SSRI (Script Sourced Rich Information) + +- [Quick Starts: Interact with SSRI-Compliant UDT Script with @ckb-ccc/udt](https://github.com/ckb-devrel/ccc/tree/master/guides/quickstart_udt.md) + ## Links - [CCC Playground](https://live.ckbccc.com/) and its [source code](https://github.com/ckb-devrel/ccc/tree/master/packages/playground) help you experiment with CCC instantly in browsers. diff --git a/guides/quickstart_udt.md b/guides/quickstart_udt.md new file mode 100644 index 00000000..7ed542bc --- /dev/null +++ b/guides/quickstart_udt.md @@ -0,0 +1,131 @@ +# Quick Starts: Interact with SSRI-Compliant UDT Script with @ckb-ccc/udt + +> The following guide uses UDT and Pausable UDT as example and assume you're using the playground environment which provides the signer. Your signer would be different based on your project setup. + +## Example 1: Prepare and Setup a UDT instance + +1. Create or setup your project with CCC (see guide [here](https://docs.ckbccc.com/index.html#md:quick-start-with-create-ccc-app-recommended)) + +2. Start up your local SSRI server through docker: + +```shell +docker run -p 9090:9090 hanssen0/ckb-ssri-server +``` + +3. Prepare the `OutPoint` of your SSRI-compliant UDT script. It's recommended to deploy your UDT script with Type ID, and the following way would allow you to get the `OutPoint` programmatically even if the script gets upgraded: + +```ts +import { ccc } from "@ckb-ccc/ccc"; +import { signer } from "@ckb-ccc/playground"; +// Note: Your signer would be different based on your project setup. + +const pudtScriptCell = await signer.client.findSingletonCellByType({ + codeHash: + "0x00000000000000000000000000000000000000000000000000545950455f4944", + hashType: "type", + args: "0xf0bad0541211603bf14946e09ceac920dd7ed4f862f0ffd53d0d477d6e1d0f0b", +}); +if (!scriptCell) { + throw new Error("pudt script cell not found"); +} +``` + +4. Prepare the Type script object of your UDT. You can provide the code hash yourself by copying from the explorer, or get it programmatically from the `OutPoint` of your UDT script. + +```ts +const pudtCodeHash = pudtScriptCell.cellOutput.type?.hash(); +if (!pudtCodeHash) { + throw new Error("PUDT code hash not found"); +} +const pudtType = { + codeHash: pudtCodeHash, + hashType: "type", + args: "0x02c93173368ec56f72ec023f63148461b80e7698eddd62cbd9dbe31a13f2b330", +}; +``` + +5. You have everything ready, now you can create an instance of your UDT and interact with it. + +```ts +const executor = new ccc.ssri.ExecutorJsonRpc("http://localhost:9090"); +const pudt = new ccc.udt.Udt(pudtScriptCell.outPoint, pudtType, { + executor, +}); +const pudtName = await pudt.name(); +const pudtIcon = await pudt.icon(); +console.log(pudtName); +// {"res":"pudt Token","cellDeps":[]} +console.log(pudtIcon); +// {"res":"data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNDgiIGhlaWdodD0iNDgiIHZpZXdCb3g9IjAgMCA0OCA0OCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPGNpcmNsZSBjeD0iMjQiIGN5PSIyNCIgcj0iMjQ ...... +``` + +The same script might have implemented multiple SSRI traits or sub-traits at the same time, but you can instantiate the same script arbitrarily with different traits as long as the script implemented the traits you want. + +```ts +const pudt = new ccc.udt.UdtPausable(pudtScriptCell.outPoint, pudtType, { + executor, +}); +const pudtEnumeratePaused = await pudt.enumeratePaused(); +console.log(pudtEnumeratePaused); +// {"res":["0xb5202efa0f2d250af66f0f571e4b8be8b272572663707a052907f8760112fe35","0xa320a09489791af2e5e1fe84927eda84f71afcbd2c7a65cb419464fe46e75085"],"cellDeps":[{"txHash":"0x98c37eabc1672c4a0a30c0bb284ed49308f0cb58b0d8791f44cca168c973e7da","index":"0"}]} +``` + +## Example 2: Generate and Send a Transaction through @ckb-ccc/udt + +1. Some of the methods allows you to generate a transaction object directly while taking care of most of the details for you. You just need to follow the guidance of the docs provided via your IDE. + +```ts +const receiverA = + "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq2jk6pyw9vlnfakx7vp4t5lxg0lzvvsp3c5adflu"; + +const { script: lockA } = await ccc.Address.fromString( + receiverA, + signer.client +); + +const pudtTransferTx = ( + await pudt.transfer(signer, [ + { + to: lockA, + amount: 10000, + }, + ]) +).res; +``` + +Many of these methods also allow you to pass in a previous `ccc.TransactionLike` object as the second argument, which allows you for example to transfer multiple UDT cells in a single transaction. + +```ts +const receiverB = + "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqflz4emgssc6nqj4yv3nfv2sca7g9dzhscgmg28x"; +const { script: lockB } = await ccc.Address.fromString( + receiverB, + signer.client +); +let combinedTransferTx = ( + await pudt.transfer( + signer, + [ + { + to: lockB, + amount: 20000, + }, + ], + pudtTransferTx + ) +).res; +``` + +2. You only need to complete the inputs of the transaction just like processing any other transactions with CCC. + +```ts +// Note: You need to connect your wallet for the following parts. You also need to have enough balance of pudt in your wallet. +combinedTransferTx = await pudt.completeBy(combinedTransferTx, signer); +await combinedTransferTx.completeFeeBy(signer); +await render(combinedTransferTx); +const combinedTransferTxHash = await signer.sendTransaction(combinedTransferTx); + +console.log(combinedTransferTxHash); +``` + +Full runnable example can be found at [here](https://live.ckbccc.com/?src=nostr:nevent1qqs8q20jvxqfsrhqw4te248qduex39dgls7qajhuc42kale0yqatdhspzemhxue69uhhyetvv9ujumn0wd68ytnzv9hxgqg5waehxw309ahx7um5wghx77r5wghxgetkqy28wumn8ghj7un9d3shjtnyv9kh2uewd9hspusjlf) diff --git a/packages/udt/README.md b/packages/udt/README.md index 5f44d16e..a4857824 100644 --- a/packages/udt/README.md +++ b/packages/udt/README.md @@ -170,7 +170,7 @@ const combinedTransferTxHash = await signer.sendTransaction(combinedTransferTx); console.log(combinedTransferTxHash); ``` -Full runnable example can be found at [here](https://live.ckbccc.com/?src=nostr:nevent1qqs8q20jvxqfsrhqw4te248qduex39dgls7qajhuc42kale0yqatdhspzemhxue69uhhyetvv9ujumn0wd68ytnzv9hxgqg5waehxw309ahx7um5wghx77r5wghxgetkqy28wumn8ghj7un9d3shjtnyv9kh2uewd9hspusjlf) +Full runnable example can be found at [here](https://live.ckbccc.com/?src=https://raw.githubusercontent.com/ckb-devrel/ccc/refs/heads/master/packages/examples/src/udt/quickstart.ts)

From 92fa2414b4f622fd32af34d43d12813604172bde Mon Sep 17 00:00:00 2001 From: Alive24 Date: Tue, 18 Feb 2025 01:01:10 +0000 Subject: [PATCH 4/4] fix: doc --- packages/ssri/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/ssri/README.md b/packages/ssri/README.md index fa388cbb..4aef4c45 100644 --- a/packages/ssri/README.md +++ b/packages/ssri/README.md @@ -38,7 +38,7 @@ ## Script-Sourced Rich Information -- Try interactive demo at [CCC App - SSRI](https://ccc-git-udtssridemo-aaaaaaaalive24.vercel.app?_vercel_share=zQkvWcsB2U9HRbpRFtF9w3xQT9msZDWb) +- Try interactive demo at [CCC App - SSRI](https://app.ckbccc.com/connected/SSRI) - Read more about SSRI on [[EN/CN] Script-Sourced Rich Information - 来源于 Script 的富信息](https://talk.nervos.org/t/en-cn-script-sourced-rich-information-script/8256). >## NOTE: This is the base package for interaction with SSRI-Compliant scripts