From 59de8254c80cb75a7bb7ea69e386000185754f39 Mon Sep 17 00:00:00 2001 From: hh Date: Thu, 27 Jun 2024 11:21:49 +0800 Subject: [PATCH] update docs for remove cli init command --- .../how-to-integrate-a-frontend.md | 2 +- docs/how-to-publish-a-contract.md | 127 ++---------------- docs/how-to-test-a-contract.md | 61 +++++++++ .../how-to-write-a-contract.md | 54 ++++++++ 4 files changed, 130 insertions(+), 114 deletions(-) diff --git a/docs/how-to-integrate-a-frontend/how-to-integrate-a-frontend.md b/docs/how-to-integrate-a-frontend/how-to-integrate-a-frontend.md index c1b23b414..71619c87f 100644 --- a/docs/how-to-integrate-a-frontend/how-to-integrate-a-frontend.md +++ b/docs/how-to-integrate-a-frontend/how-to-integrate-a-frontend.md @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 9 --- # How to integrate with a front-end diff --git a/docs/how-to-publish-a-contract.md b/docs/how-to-publish-a-contract.md index f04926b8c..0fd222a87 100644 --- a/docs/how-to-publish-a-contract.md +++ b/docs/how-to-publish-a-contract.md @@ -1,121 +1,34 @@ --- -sidebar_position: 9 +sidebar_position: 8 --- # How to Publish a Contract to NPM -## What is a Smart Contract Library? -A smart contract library can provide methods which can be reused in many contracts. Developers can use existing libraries to reduce the cost of developing their own contracts. +## Create and Publish a Contract Using sCrypt CLI -A smart contract library is different from a smart contract in these ways: - -* A smart contract library can not have any public/entry `@method`s, which means a library can not be deployed or called directly through a tx. They can only be called within a smart contract or another library. - -* A smart contract library can not have any stateful properties, i.e. `@prop(true)` properties. But a property declared as `@prop()` is fine. - -## Write a Smart Contract Library - -Using `sCrypt` we can create a smart contract library class like this: - -```ts -class MyLib extends SmartContractLib { - - @prop() - readonly buf: ByteString; - - constructor(buf: ByteString) { - super(...arguments); - this.buf = buf; - } - - @method() - append(content: ByteString) { - this.buf += content; - } - - @method() - static add(x: bigint, y: bigint): bigint { - return x + y; - } - -} -``` - -A smart contract library can be declared as a class that extends `SmartContractLib`. It may also have `@prop`s and `@method`s like smart contracts which have the same rules [introduced before](./how-to-write-a-contract). A smart contract library can be used within `@method`s like this: - -```ts -class MyContract extends SmartContract { - @method() - public unlock(x: ByteString) { - let myLib = new MyLib(hexToByteString('0123')); - myLib.append(x); - assert(MyLib.add(1n, 2n) === 3n, 'incorrect sum'); - } -} -``` - -## Test a Smart Contract Library - -You can test your smart contract library as a normal class, for example, writing some unit tests: - -```ts -describe('Test SmartContractLib `MyLib`', () => { - it('should pass unit test successfully.', () => { - expect(MyLib.add(1n, 2n)).to.eq(3n) - }) -}) -``` - -Also you can write a smart contract using the library, then have some tests for the contract, like: - -```ts -class TestLib extends SmartContract { - @method - public unlock(x: bigint) { - assert(MyLib.add(1n, 2n) == x, 'incorrect sum') - } -} - -describe('Test SmartContractLib `Lib`', () => { - before(async() => { - await TestLib.loadArtifact() - }) - - it('should pass integration test successfully.', () => { - let testLib = new TestLib() - let result = testLib.verify(self => self.unlock(3n)) - expect(result.success, result.error).to.be.true - } -}) - -``` - -## Create and Publish a Library Project Using sCrypt CLI - -The following command will create a demo `sCrypt` library along with tests and scaffolding: +The following command will create a demo `sCrypt` project along with tests and scaffolding: ```sh -npx scrypt-cli project --lib +npx scrypt-cli project ``` -Note the `lib` option is turned on. -You can publish the library on [NPM](https://www.npmjs.com/) by running the following command in the project's root directory: +You can publish the project on [NPM](https://www.npmjs.com/) by running the following command in the project's root directory: ```sh npm publish ``` -This will build the project and publish it on NPM. After the library is published, users can simply import it in any other project just like regular NPM packages. +This will build the project and publish it on NPM. After the package is published, users can simply import it in any other project just like regular NPM packages. :::note Named imports are not supported yet. You should only import like the following. ::: ```ts -import { MyLib } from “my_package” +import { MyContract } from "my_package" ``` ### Advanced @@ -126,32 +39,20 @@ For the import system working properly, you should always publish the auto-gener node_modules |__ my_package |__ dist - |__ myLib.js - |__ myLib.d.ts + |__ myContract.js + |__ myContract.d.ts |__ artifacts - |__ myLib.scrypt + |__ myContract.json |__ scrypt.index.json … ``` -The `scrypt.index.json` file will be generated at TypeScript compile time in the same directory of your `tsconfig.json` which should be placed in the root folder. It shall not be moved or modified manually. The folder for auto-generated `.scrypt` files (`artifacts` in the upper file tree) can be changed by configuring the `outDir` option in `tsconfig.json`, like: - -```json -"compilerOptions": { - "plugins": [ - { - "transform": "scrypt-ts/dist/transformation/transformer", - "transformProgram": "true", - "outDir": "my_scrypts_dir" - } - ] -} -``` +The `scrypt.index.json` file will be generated at TypeScript compile time in the same directory of your `tsconfig.json` which should be placed in the root folder. It shall not be moved or modified manually. -You should always publish the auto-generated sCrypt files along with the package. +You should always publish the auto-generated artifacts files along with the package. -## Related Tools +## Related Packages ### `scrypt-ts-lib` -It’s a collection of smart contract libraries provided by us. You can find some useful tools [here](https://github.com/sCrypt-Inc/scrypt-ts-lib). Also you are welcome to contribute. +It’s a collection of smart contract libraries provided by us. You can find some useful packages [here](https://github.com/sCrypt-Inc/scrypt-ts-lib). Also you are welcome to contribute. diff --git a/docs/how-to-test-a-contract.md b/docs/how-to-test-a-contract.md index e329c77d3..75da434b2 100644 --- a/docs/how-to-test-a-contract.md +++ b/docs/how-to-test-a-contract.md @@ -301,3 +301,64 @@ or ```sh npm run test:testnet ``` + + +# How to Test a Contract Library + +You can test your smart contract library as a normal class, for example, writing some unit tests: + +```ts + +class MyLib extends SmartContractLib { + + @prop() + readonly buf: ByteString; + + constructor(buf: ByteString) { + super(...arguments); + this.buf = buf; + } + + @method() + append(content: ByteString) { + this.buf += content; + } + + @method() + static add(x: bigint, y: bigint): bigint { + return x + y; + } + +} + +describe('Test SmartContractLib `MyLib`', () => { + it('should pass unit test successfully.', () => { + expect(MyLib.add(1n, 2n)).to.eq(3n) + }) +}) +``` + +Also you can write a smart contract using the library, then have some tests for the contract, like: + +```ts +class MyContract extends SmartContract { + @method + public unlock(x: bigint) { + assert(MyLib.add(1n, 2n) == x, 'incorrect sum') + } +} + +describe('Test `MyLib` with `MyContract`', () => { + before(async() => { + await MyContract.loadArtifact() + }) + + it('should pass integration test successfully.', () => { + let instance = new MyContract() + await instance.deploy(1) + const call = async () => instance.methods.unlock(3n) + await expect(call()).not.to.be.rejected + } +}) + +``` diff --git a/docs/how-to-write-a-contract/how-to-write-a-contract.md b/docs/how-to-write-a-contract/how-to-write-a-contract.md index 60209937b..3b419a6e9 100644 --- a/docs/how-to-write-a-contract/how-to-write-a-contract.md +++ b/docs/how-to-write-a-contract/how-to-write-a-contract.md @@ -916,3 +916,57 @@ static add(a: bigint, b: bigint): bigint { :::note `**` is not supported currently. ::: + + + + +## Smart Contract Library + +A smart contract library can provide methods which can be reused in many contracts. Developers can use existing libraries to reduce the cost of developing their own contracts. + +A smart contract library is different from a smart contract in these ways: + +* A smart contract library can not have any public/entry `@method`s, which means a library can not be deployed or called directly through a tx. They can only be called within a smart contract or another library. + +* A smart contract library can not have any stateful properties, i.e. `@prop(true)` properties. But a property declared as `@prop()` is fine. + +### Write a Smart Contract Library + +Using `sCrypt` we can create a smart contract library class like this: + +```ts +class MyLib extends SmartContractLib { + + @prop() + readonly buf: ByteString; + + constructor(buf: ByteString) { + super(...arguments); + this.buf = buf; + } + + @method() + append(content: ByteString) { + this.buf += content; + } + + @method() + static add(x: bigint, y: bigint): bigint { + return x + y; + } + +} +``` + +A smart contract library can be declared as a class that extends `SmartContractLib`. It may also have `@prop`s and `@method`s like smart contracts which have the same rules [introduced before](./how-to-write-a-contract). A smart contract library can be used within `@method`s like this: + +```ts +class MyContract extends SmartContract { + @method() + public unlock(x: ByteString) { + let myLib = new MyLib(hexToByteString('0123')); + myLib.append(x); + assert(MyLib.add(1n, 2n) === 3n, 'incorrect sum'); + } +} +```