pw-core is the front-end sdk of pw-sdk
You can install pw-core to your project with npm
# in your project root
$ npm install @lay2/pw-core --saveOr with yarn
# in your project root
$ yarn add @lay2/pw-coreLet's see how to send CKB with pw-core.
importPWCore,{EthProvider,PwCollector,ChainID,Address,Amount,AddressType,}from'@lay2/pw-core';// insdie an async scopeconstpwcore=awaitnewPWCore('https://ckb-node-url').init(newEthProvider(),// a built-in Provider for Ethereum env.newPwCollector()// a custom Collector to retrive cells from cache server.);consttxHash=awaitpwcore.send(newAddress('0x26C5F390FF2033CbB44377361c63A3Dd2DE3121d',AddressType.eth),newAmount('100'));That's it! If CKB transaction (with Ethereum wallets, e.g. MetaMask) is the only thing you need, you can already start your integration with pw-core.
However, if you need more features, such as adding multiple outputs, setting data, or adding custom lock/type scripts, you can always implement you own builder extends the Builder class. If you have more requirements with retriving unspent cells, a custom cell collector based on Collector is a good choice. The same approach applies to Signer / Hasher / Provider. In fact, you will find that almost every aspect of buiding a transaction can be customized to meet your demands. This is because we have well encapsulated the transaction process as build -> sign -> send, and any kind of transaction can be created and sent given a builder and a signer. For example, the basic send method used in the Hello World example is implented like this:
// code from: https://github.com/lay2dev/pw-core/blob/master/src/core.ts#L80import{transformers}from'ckb-js-toolkit'import{Address,Amount}from'./models'import{SimpleBuilder}from'./builders'import{EthSigner}from'./signers'asyncsend(address: Address,amount: Amount,feeRate?: number): Promise<string>{constsimpleBuilder=newSimpleBuilder(address,amount,feeRate);const=newEthSigner(address.addressString);returnthis.sendTransaction(simpleBuilder,ethSigner);}asyncsendTransaction(builder: Builder,signer: Signer): Promise<string>{returnthis.rpc.send_transaction(transformers.TransformTransaction(awaitsigner.sign((awaitbuilder.build()).validate())));}Finally, here is an example project which shows how to implement custom classes to achieve certain features. The SDCollector can collect unspent cells with a ckb-indexer, while the SDBuilder can build transactions for creating / updating / deleting cells. More over, the built-in EthProvider and EthSigner (along with Keccak256Hasher) are used to make this dApp runnable in Ethereum enviromment (such as MetaMask).
We only provide two types of interfaces, one is the most commonly used and the other is fully customizable. For example, you can use
pwcore.sendto just send some CKB, and usepwcore.sendTransactionto send any type of transactions. More over, you can even usepwcore.rpcto get direct access to ckb rpc calls, which enables abilities far beyond sending transactions.
Talk is cheap, let's show some code.
/* ------ Address ------ *//* create an Address instance from a CKB address */constckbAddress=newAddress('ckb1qyqdmeuqrsrnm7e5vnrmruzmsp4m9wacf6vsxasryq',AddressType.ckb);/* create an Address instance from an Ethereum address */constethAddress=newAddress('0x308f27c8595b2ee9e6a5faa875b4c1f9de6b679a',AddressType.eth);/* get the original address string */console.log('ckb: ',ckbAddress.addressString)console.log('eth: ',ethAddress.addressString)// ckb: ckb1qyqdmeuqrsrnm7e5vnrmruzmsp4m9wacf6vsxasryq// eth: 0x308f27c8595b2ee9e6a5faa875b4c1f9de6b679a/* get the corresponding CKB address */console.log('ckb: ',ckbAddress.toCKBAddress())console.log('eth: ',ethAddress.toCKBAddress())// ckb: ckb1qyqdmeuqrsrnm7e5vnrmruzmsp4m9wacf6vsxasryq// eth: ckt1q3vvtay34wndv9nckl8hah6fzzcltcqwcrx79apwp2a5lkd07fdxxvy0yly9jkewa8n2t74gwk6vr7w7ddne5jrkf6c/* get the corresponding lock script hash (with the toHash method of class Script) */console.log('ckb: ',ethAddress.toLockScript().toHash())console.log('eth: ',ethAddress.toLockScript().toHash())// ckb: 0xe9e412caf497c69e9612d305be13f9173752b9e75bc5a9b6d1ca51eb38d07d59// eth: 0x0963476f28975bf93da673cd2442bd69c4b2d4e720af5a67ecece8a03b8926b5/* check if the address is an ACP address */console.log('ckb: ',ckbAddress.isAcp())console.log('eth: ',ethAddress.isAcp())// false// true// get the minimal CKB amount (an Amount instance) you can transfer to this addressconsole.log('ckb: ',ckbAddress.minPaymentAmount().toString()+' CKB')console.log('eth: ',ethAddress.minPaymentAmount().toString()+' CKB')// 61 CKB// 0.00000001 CKB/* ------ Script ------ */constlockScript=addressCkb.toLockScript();constlockScriptHash=lockScript.toHash();constaddress1=Address.fromLockScript(lockScript);constaddress2=lockScript.toAddress();console.log(addressEth.toLockScript().sameWith(addressCkbFull.toLockScript()));//true/* ------ Amount ------ */constckb100=newAmount('100');constshannon100=newAmount('100',AmountUnit.shannon);constusdt=newAmount('1234.5678',6);// Assume usdt's decimals is 6/* format */console.log(`${ckb100.toString()} CKB is ${ckb100.toString(AmountUnit.shannon,{commify: true})} Shannon`);// 100 CKB is 1,000,000 Shannonconsole.log(`${shannon100.toString(AmountUnit.shannon)} Shannon is ${shannon100.toString()} CKB`)// 100 Shannon is 0.000001 CKBconsole.log(`${usdt.toString(6,{fixed: 2,commify: true})} USDT is rounded from ${usdt.toString(6,{pad: true})} USDT`);// 1,234.57 USDT is rounded from 1234.567800 USDT/* compare */console.log('100 CKB is greater than 100 Shannon: ',ckb100.gt(shannon100));console.log('100 CKB is less than 100 Shannon: ',ckb100.lt(shannon100));// 100 CKB is greater than 100 Shannon: true// 100 CKB is less than 100 Shannon: falseconsole.log('100 Shannon is equal to 0.000001 CKB: ',shannon100.eq(newAmount('0.000001')));// 100 Shannon is equal to 0.000001 CKB: true/* calculate */console.log(`100 CKB + 100 Shannon = ${ckb100.add(shannon100).toString()} CKB`);console.log(`100 CKB - 100 Shannon = ${ckb100.sub(shannon100).toString()} CKB`);// 100 CKB + 100 Shannon = 100.000001 CKB// 100 CKB - 100 Shannon = 99.999999 CKB// Amount is assumed with unit, so if we want to perform multiplication or division, the best way is to convert the Amount instance to JSBI BigInt, and convert back to Amount instance if necessary.constbn=JSBI.mul(ckb100.toBigInt(),JSBI.BigInt(10));constamount=newAmount(bn.toString())console.log(`100 CKB * 10 = ${amount.toString(AmountUnit.ckb,{commify: true})} CKB`);// 100 CKB * 10 = 1,000 CKB/* ------ Cell ------ *//* load from blockchain with a rpc instance and an outpoint */constcell1=Cell.loadFromBlockchain(rpc,outpoint);/* convert rpc formated data to a Cell instance */constcell2=Cell.fromRPC(rpcData);/* check how many capacity is occupied by scripts and data */constoccupiedCapacity=cell1.occupiedCapacity();/* check if the cell's capacity is enough for the actual size */cell1.spaceCheck();/* check if the cell is empty (no data is stored) */cell2.isEmpty()/* adjust the capacity to the minimal value of this cell */cell2.resize();/* set / get amount of an sUDT cell */constcell3=cell2.clone();cell3.setSUDTAmount(newAmount(100));console.log('sUDT amount: ',cell3.getSUDTAmount().toString());// sUDT amount: 100/* playing with data */cell1.setData('data');cell2.setHexData('0x64617461');console.log('data of cell 1: ',cell1.getData());console.log('data of cell 2: ',cell1.getData());console.log('hex data of cell 1: ',cell1.getHexData());// data of cell 1: data// data of cell 2: data// hex data of cell 1: 0x64617461
CKB dApp development is mostly about manipulating cells. However, when we actually try to design a dApp, it turns out that we are always dealing with transactions. If you ever tried to build a CKB transaction, you'll definitely be impressed (or most likely, confused) by the bunch of fields. Questions may be asked like:
There are data structures like 'CellInput' and 'CellOutput', but where is 'Cell' ?
How to calculate the transaction fee? How to adjust the change output?
What kind of unit ( CKB or Shannon) and format (mostly hex string) to use?
Things are different with pw-core. Let's see the actual constructor of RawTransaction
// code from: https://github.com/lay2dev/pw-core/blob/master/src/models/raw-transaction.ts#L7exportclassRawTransactionimplementsCKBModel{constructor(publicinputCells: Cell[],publicoutputs: Cell[],publiccellDeps: CellDep[]=[PWCore.config.defaultLock.cellDep,PWCore.config.pwLock.cellDep,],publicheaderDeps: string[]=[],publicreadonlyversion: string='0x0'){this.inputs=inputCells.map((i)=>i.toCellInput());this.outputsData=this.outputs.map((o)=>o.getHexData());}// ...}It's easy to findout that both inputs and outputs are Array of cells, and the low-level details and transformations are done silently. And yes, we have the 'Cell' structure.
Although pw-core works closely with pw-lock (both projects are components of pw-sdk), you can still use the default blake2b lock or your own lock, as long as the corresponding builder, signer and hasher are implemented. In fact, the
Blake2bHasheris already built-in, and aCkbSigneris very likely to be added in the near future. With the progress of pw-sdk, more algorithm be added to the built-in collections, such asSha256HasherandP256Signer.
You can find a detailed API Document Here.
Currently pw-core is still at a very early stage, and all kinds of suggestions and bug reports are very much welcomed. Feel free to open an issue, or join our Discord server to talk directly to us. And of couse, a star is very much appreciated :).