Skip to content

Commit 8656500

Browse files
Keith-CYKeith-CY
committed
docs: add a draft of kuai proposal
Add a draft of kuai proposal to elaborate on the motivation, design and schedule.
1 parent 331278d commit 8656500

File tree

1 file changed

+319
-0
lines changed

1 file changed

+319
-0
lines changed

‎README.md‎

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
## Problems to solve
2+
3+
There are three obvious obstables hindering the development of DApps on CKB.
4+
5+
### First: separate runtimes
6+
7+
CKB adopts Cell model which is a generalization of UTXO model so only a **function of state verification** is running on-chain, that's the core of a DApp and theoretically that's all of a DApp.
8+
9+
But a real-word DApp is for users who are not good at mathematics or programming so the logic of the DApp will be exposed by a graphical interface and a set of prescribed actions. The team of a DApp has to
10+
11+
1. re-implement **function of state verification on-chain** off-chain for testing;
12+
2. define a **state transition equation** following the **function of state verification** for prescribed actions;
13+
3. define algorithms to get ideal parameters for the **state transition equation**, namely `input cells` from CKB, and implement a server to map kv data into relational data for graphical interface.
14+
15+
A mass of off-chain works are introduced because runtimes of on-chain and off-chain are separate and follow exclusive paradigms.
16+
17+
**function of state verification on-chain** is totally a pure function which returns code_0 for success and code_other for failure, all its arguments are determined so the result is predictable.
18+
19+
**function of state verification off-chain** is a rehearsal or replay of **function of state verification off-chain**, they share the same logic but the one off-chain may be re-implemented because the one on-chain is based on rust which is hard for most programmers.
20+
21+
**state transition equation** is reversed from the **function of state verification**, this is easy to understand and used in ethereum contract,
22+
23+
```
24+
// let's define the function of state verification and expect it be be 0
25+
fn(action)(current_state, new_state) = 0
26+
27+
// then the state transition equation will be deduced
28+
new_state = fn'(actions)(current_state)
29+
30+
// and we get the state transition function
31+
const fn_transition = fn'(actions)
32+
```
33+
34+
What's even crazy is that **state verification** is **functional** while **state transition** might be in **object-oriented** style because `actions` in `fn'(actions)` is from a set of pre-defined actions on graphical interface and could be pipelined in various order.
35+
36+
Besides, the **function of state transition** has only one parameter `current_state`, which is determined by algorithms of gathering cells on-chain, the algorithms will be realized by complex mechanism due to consideration of engineering and concurrency issues caused by cell model.
37+
38+
These concepts are too obscure and leading to a steep learning curve for DApp developers.
39+
40+
### Second: Lack of development paradigm
41+
42+
There's no clear and unified paradigm for development, every DApp project could have various assumptions, project structure, workflow, and APIs. By the variety, each DApp grows into an insulated island because it takes too much to understand the design, implementation of a DApp. It's also hard to interoperate another DApp because its APIs are unpredictable.
43+
44+
### Third: Fragmented devtools
45+
46+
Now there're many devtools for specific goals or domains but it takes too much to master them all.
47+
48+
#### Contract development
49+
- Capsule: https://github.com/nervosnetwork/capsule, a development framework for creating smart contract scripts in Rust for Nervos' CKB layer 1 blockchain. Capsule is designed to provide an out-of-the-box solution that helps Nervos developers accomplish common tasks quickly and painlessly.
50+
- CKB standalone debugger: https://github.com/nervosnetwork/ckb-standalone-debugger, a standalone debugger enabling off-chain contract development.
51+
52+
#### Local network
53+
- Tippy: https://github.com/nervosnetwork/tippy, tippy is a sandbox development environment available to Nervos CKB developers. Throughout the development cycle, developers can use Tippy, which allows them to develop, deploy and test DApps in a secure and deterministic environment.
54+
55+
#### Aggregation service
56+
- CKB Indexer: https://github.com/nervosnetwork/ckb-indexer,a standalone service for creating cell and transaction indexes as an alternate solution.
57+
- Lumos: https://github.com/ckb-js/lumos, lumos is a full-featured JavaScript/TypeScript based DApp framework for Nervos CKB.
58+
- Mercury: https://github.com/nervosnetwork/mercury, building on top of ckb-indexer, Mercury provides handy integration features for Nervos CKB.
59+
60+
What's worse, some DApp teams found the devtools were not enough for them so they had to develop tools for themselves, leading to more fragmented.
61+
62+
## How other ecologies are solving these problems
63+
64+
For the separate runtimes issue introduced by UTXO model, there's a framework named `run`(https://run.network/) aiming at propagating a token protocol for universal DApps.
65+
66+
A data model named `Jig` is brought in as the most basic unit of an interactive object to build a skyscraper from bricks. Imagine we are building a toy vehicle with lego blocks, every two blocks can be easily connected even they are in various shapes because they share a unified interface.
67+
68+
![lego brick](https://www.brickshop.eu/components/com_virtuemart/shop_image/product/LEGO_Plaat_2x2_B_524d1fcf58a12.jpg)
69+
70+
And all advanced data models are derived from `Jig`, like `Code`, `Token`, work for specific functions, can be connected to each other because they share the most basic interfaces.
71+
72+
![lego brick](https://www.lego.com/cdn/product-assets/element.img.lod5photo.192x192/6276858.jpg)
73+
![lego brick](https://www.lego.com/cdn/product-assets/element.img.lod5photo.192x192/6345886.jpg)
74+
75+
In terms of development paradigm and devtools, ethereum community has given a good enough answer. The most popular development framework in ethereum community is `hardhat`(https://hardhat.org/), which names itself as **professional development environment** and is super similar to a mature build system.
76+
77+
It takes care of building/debugging/testing/deployment and is extensible by plugins and tasks so developers could finish their work within a framework.
78+
79+
By the support of hardhat, projects will follow the same convention and generate a contract-specific SDK for outside users.
80+
81+
## Kuai Project
82+
83+
`Kuai` project is a framework to solve problems mentioned above, inspired by [actor model](https://www.wikiwand.com/en/Actor_model), [run](https://run.network/), [hardhat](https://hardhat.org/) and other tools popular in the community.
84+
85+
`Kuai` includes a unified paradigm for development, a set of conventions, fine-grind all-in-one devtools with SDKs and a general aggregation service.
86+
87+
### Unified paradigm for development
88+
89+
Two abstractions will be promoted in `Kuai`: `Data storage` and `Data manipulation`
90+
91+
#### Abstraction of data storage
92+
93+
There'll be three basic data models used in `Kuai` based DApps: `Data`, `Code`, `MultiCoin Token`
94+
95+
##### Data
96+
97+
The basic function of cells in CKB is storing data. But data are meaningless without schema, so the first basic model introduced by `Kuai` is named `Data` which is used to transform plain data into a structured data with schema.
98+
99+
Note that a `Data` model could be a group of cells matching the same pattern and working as an entity so it could be regarded as a virutal DApp. Say we have 2 DApps in `School Roster Data` models, each of them consists of many `Student Data` models. And we are going to build a `Sports Meeting` DApp, a new `Sports Meeting Data` model could be created and consists of partial `Student Data` from School A and B respectively, it should work as same as a `School Roster` DApp.
100+
101+
##### Code
102+
103+
`Code` model is extended from `Data` model and used for scripts. A `Code` model has not only attributes, but also methods. In other words, it's not only read-/writable, but also executable. `Code` model's data/state could be updated by some rules rather than a simple `set` method inherited from the `Data` model.
104+
105+
##### MultiCoin Token
106+
107+
Token is a general use case that should have ability of transferring between DApps, so the third model to introduce is `MultiCoin Token`, which is specialized from `Code` model with specific attributes and methods.
108+
109+
#### Abstraction of data manipulation
110+
111+
DApps can read states from each other freely because data/states are arranged uniformly by the abstraction of data storage.
112+
113+
DApps can also communicate with each other freely if data manipulation has been abstracted.
114+
115+
##### Data
116+
117+
A `Data` model should have 7 basic interfaces
118+
119+
- New(pattern): create an `Data` model binding to specified cells, as a DApp located by the pattern, ps: it's a virtual DApp rather than an explicit DApp, but because cells are following the same rule, they can work together as an entity.
120+
- Destroy(): remove state and turn the cells into empty
121+
- Duplicate(): create a `Data` model from a instance
122+
- Sync(blockNumber?): will load and update data from the chain at latest(or specific block) global state
123+
- Get(path): will read value of specified path
124+
- Set(path, value): will set given value at specified path
125+
- Delete: (path): remove key/value at specified path
126+
127+
##### Code
128+
129+
A `Code` model should have 5 more interfaces than `Data` model
130+
131+
- Deploy(): deploy the script on the chain
132+
- Extend(code): extends from an existing `Code` model for overriding
133+
- Upgrade(): upgrade the script on the chain
134+
- Run(method: string, params: Array<any>): call a method of the script to update its state
135+
- Link(abi: Array<object>): instantiate a script SDK from ABI
136+
137+
##### MultiCoin Token
138+
139+
A generally used token must have some methods based on `Code`
140+
141+
- Metadata(tokenId, metadata?): a setter/getter to the metadata of a specific token id including `name`, `symbol`, `tokenURI`, `totalSupply`)
142+
- Mint(tokenId, amount): Mint a token
143+
- Send(from, to, tokenId, amount): Send a token
144+
- Stake(address, dapp, tokenId, amount, locktime?): stake into a dapp and get staking tokens
145+
- Redeem(address, dapp, tokenId, amount): unstake from a dapp and burn a staking token
146+
- Lock(address, amount, tokenId, locktime): lock tokens, for cases like pre-sale, bounty of a team
147+
- Unlock(address, tokenId, amount): unlock tokens
148+
- Combine(token): combine two `MultiCoin Token` models into one
149+
- GetBalance(address, tokenId): get token balance of a given address
150+
151+
152+
Notice, all actions will be grouped and finalized together, viz. `mint`/`send` multiple token id will be finalized with a single transaction
153+
154+
#### Reactive Lazy Evaluation
155+
156+
As mentioned above
157+
158+
> Notice, all actions will be grouped and finalized together, viz. `mint`/`send` multiple token id will be finalized with a single transaction
159+
160+
All actions/manipulations adopted on a model will be cached and evaluated at the end of the pipeline.
161+
162+
```javascript
163+
const model = new Data()
164+
model.action_1()
165+
model.action_2()
166+
// ...
167+
modeol.action_n()
168+
169+
/**
170+
* get a structure with initial state and actions
171+
*
172+
* {
173+
* state,
174+
* actions: [action_1, action_2, action_3, ..., action_n]
175+
* }
176+
*
177+
* and calling the finalize() to evaluate new state
178+
*/
179+
180+
model.finalize()
181+
182+
/**
183+
*
184+
* {
185+
* state: new_state,
186+
* actions: [],
187+
* }
188+
*
189+
*/
190+
191+
```
192+
193+
Lazy evaluation is beneficial to the following points:
194+
195+
1. state of the model could be traversed for debugging
196+
2. actions could be revoked easily to find the best path of state transition.
197+
3. inspector(or other dependencies) could be injected to enhance development
198+
199+
#### Model Tree
200+
201+
There would be multiple levels of `Data` models constructing a model tree.
202+
203+
Every cell on CKB could be treated as a DApp because every cell has its own state and script while a group of cells using the same script should also be treated as a DApp because they adopt the same logic on a broader state.
204+
205+
Besides, if a DApp_A wants to interact with another DApp_B, stateof DApp_B would be a part of DApp_A's state so the models would be like
206+
207+
```mermaid
208+
flowchart BT
209+
210+
cell_a_0_model --> dapp_a_sub_model
211+
cell_a_1_model --> dapp_a_sub_model
212+
cell_a_n_model --> dapp_a_sub_model
213+
dapp_a_sub_model --> dapp_a_model
214+
215+
cell_b_0_model --> dapp_b_model
216+
cell_b_1_model --> dapp_b_model
217+
cell_b_n_model --> dapp_b_model
218+
dapp_b_model --> dapp_a_model
219+
```
220+
221+
### Conventions
222+
223+
`Kuai-convention` is a set of conventions for the implementation reference of `Kuai-runtime` and the usage guide of `Kuai-runtime`, such as:
224+
225+
- serialization - cell state layout to prevent conflict between different contract interactions
226+
- ABI - Application Binary Interface for cell model
227+
- structure - project structure
228+
- sequencer - define how to sort (aggregate) user requests
229+
- storage - A series of schemes on how to persist data, such as serialization schemes, etc.
230+
231+
### Fine-grind devtools
232+
233+
The paradigm and conventions will be instructed by `Kuai` with a fine-grind devtool named `Kuai-runtime`, similar to nx(https://nx.dev/) which provides basic features of a build system and extensible for tasks and plugins.
234+
235+
Basic features delivered by `Kuai` build system:
236+
- Clear project structure
237+
- Compile
238+
- Debug
239+
- Release
240+
- Debug
241+
- Break point
242+
- Console
243+
- Inspector
244+
- Test
245+
- Run specific cases
246+
- Generate a mock transaction
247+
- Helpers as clear state, rollback
248+
- Deployment
249+
- Configuration management
250+
- Multiple network
251+
- Hd wallet
252+
- Base contracts/scripts
253+
254+
Possibly included tasks/plugins are as follow:
255+
- cycle reporter
256+
- script sizer
257+
- test-coverage
258+
- document
259+
- debugger remover
260+
- typechain: https://github.com/dethcrypto/TypeChain/
261+
- storage layout: https://www.npmjs.com/package/hardhat-storage-layout, when to use on-chain/off-chain data
262+
263+
`Kuai-runtime` covers on-chain and off-chain parts of a project, implements the interface defined by `Kuai-convention`, shielding implementation details and provides easy-to-use APIs.
264+
265+
`Kuai-runtime` also provides friendly libraries/modules for building, sending, and managing transactions, which will be elaborated on in section `General aggregation service`.
266+
267+
### General aggregation service
268+
269+
Now there are two classic types of DApp running on CKB
270+
1. based on the general cell model: e.g. Force Bridge, Portal Wallet...
271+
2. based on the SMT(sparse merkle tree, https://github.com/nervosnetwork/sparse-merkle-tree) half-rollup like: e.g. CoTA NFT, dotbit, sub-accounting...
272+
273+
`Kuai`'s aggregation service would cover these two cases for general usages and has following components:
274+
275+
- Merkle X Storage - Generate proof which stored in on-chain. And persist data in off-chain.
276+
- Sequencer - Combine multiple requests into one to avoid [concurrency issue](https://iohk.io/en/blog/posts/2021/09/10/concurrency-and-all-that-cardano-smart-contracts-and-the-eutxo-model/).
277+
- Transaction Builder Factory (OnChainStateUpdator) - Build transactions that update on-chain state.
278+
- CkbNodeClient - Interact with chains, such as query transaction status, etc.
279+
- Client-side SDK - Common wallet integration, e.g MetaMask(sign via EIP712 if possible), TronLink, CardanoWallet…
280+
- Scheduler - Scheduling various sub-services, such as Sequencer and Merkle X Storage.
281+
282+
![runtime-level drawio (2) (1)](https://user-images.githubusercontent.com/107106858/190947666-bfbdd975-1f04-4fc4-841c-37b357e31e75.png)
283+
284+
The aggregation service would run as a sub module in DApp's server
285+
286+
![kuai-runtime drawio (2) (1)](https://user-images.githubusercontent.com/107106858/190947648-4a8f401b-955c-4e90-b84e-b6f6e802dad5.png)
287+
288+
289+
## Website
290+
291+
Last but not least, as an open source project, `Kuai` would be introduced to developers with good documentation and rich examples, including:
292+
- Tutorials
293+
- Developer Documentation
294+
- API documentation
295+
296+
## Roadmap
297+
- M1 ~ M2
298+
- Construct a build system similar to https://nx.dev/, only for project structure, basic tasks, and plugins
299+
- Design storage paradigm
300+
- Design action paradigm
301+
- Design workflow with base contracts/scripts
302+
- M3 ~ M4
303+
- Implements SDK following the designed paradigm and workflow with base contracts/scripts
304+
- Design generally used tasks and plugins
305+
- Cycle reporter
306+
- Script sizer
307+
- Test-coverage
308+
- Document
309+
- Debugger remover
310+
- Typechain: https://github.com/dethcrypto/TypeChain/
311+
- Storage layout: https://www.npmjs.com/package/hardhat-storage-layout, when to use on-chain/off-chain data
312+
- Design local network debug/test/deploy tools
313+
- M5
314+
- Implement tasks/plugins
315+
- Implement local network
316+
- Implement debug/test/deploy tools
317+
- M6
318+
- Use the project to deliver a simple .bit dapp
319+

0 commit comments

Comments
 (0)