From 3981c1654323a0d3826794b561a07302910a0b4e Mon Sep 17 00:00:00 2001 From: jiyoung Date: Mon, 23 Dec 2024 03:46:28 +0900 Subject: [PATCH 1/2] docs(readme): add usage code --- README.md | 196 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 147 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 69f3bf7..fd322bd 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,170 @@ -# ain-js -AI Network Blockchain SDK for javascript (or typescript). +# AIN Blockchain SDK -## API Documentation -API documentation is available at https://ainblockchain.github.io/ain-js/. - -## Quick start -Start with the quick start section in the [online docs](https://docs.ainetwork.ai/ain-blockchain/developer-guide/getting-started). +[![npm version](https://img.shields.io/npm/v/@ainblockchain/ain-js.svg)](https://npmjs.org/package/@ainblockchain/ain-js) +![npm-downloads](https://img.shields.io/npm/dm/@ainblockchain/ain-js) +![license](https://img.shields.io/badge/license-MPL--2.0-blue) +A simple library for JavaScript and TypeScript to interact with AI Network via [JSON RPC API](https://github.com/ainblockchain/ain-blockchain/blob/master/JSON_RPC_API.md). ## Installation + +```sh +$ npm install @ainblockchain/ain-js ``` -yarn add @ainblockchain/ain-js -``` -## Examples -### A Simple Example +## Usage + +The full API of this library can be found in [API document](https://ainblockchain.github.io/ain-js), along with [code examples](https://github.com/ainblockchain/quickstart). The following code shows how to create a wallet account using the wallet API. + +### Create Wallet + +```js +const Ain = require('@ainblockchain/ain-js').default; + +const ain = new Ain('https://testnet-api.ainetwork.ai', 'wss://testnet-event.ainetwork.ai', 0); + +function main() { + const accounts = ain.wallet.create(1); + + console.log(accounts[0]); +} + +main(); + +// output example: +// { +// address: '0xb2585543Cfcfb79CF73a1a14b2DfBC411913940F', +// private_key: '...', +// public_key: '...' +// } ``` -const Ain = require('./lib/ain').default; -const ain = new Ain('http://localhost:8081/', 'ws://localhost:5100/'); -// or const ain = new Ain('https://testnet-api.ainetwork.ai/', 'wss://testnet-event.ainetwork.ai/'); - -ain.wallet.create(1); - -console.log(ain.wallet.accounts); -/* -{ - '0xb2585543Cfcfb79CF73a1a14b2DfBC411913940F': { - address: '0xb2585543Cfcfb79CF73a1a14b2DfBC411913940F', - private_key: 'd910c1835eaa89f15452aa3f0bd95f61fb9a04464150e37d617a40ed0071558c', - public_key: '008bcc621aed85140b97d71b3aa5a88e56fbdc0d5d17b2297ec2d3da2edf3b0594676981ebf16ec3490ddb8f3ba4d4aaf77d5055256f1c044474a7aa22704f60' - } + +### Read and Write Data + +```js +const Ain = require('@ainblockchain/ain-js').default; + +const ain = new Ain('https://testnet-api.ainetwork.ai', 'wss://testnet-event.ainetwork.ai', 0); + +async function main() { + const address = ain.wallet.addAndSetDefaultAccount('YOUR_PRIVATE_KEY'); + + // write value to db + const result = await ain.db.ref('YOUR_DATA_PATH').setValue({ + value: 'hello', + gas_price: 500, + timestamp: Date.now(), + nonce: -1, + }); + + // read value from db + const data = await ain.db.ref('YOUR_DATA_PATH').getValue(); + console.log(data); } -*/ -const accounts = ain.db.ref('/accounts').getValue().then(result => { - console.log(result); -}); +main(); ``` -### More Use Cases -#### [ainize-js](https://github.com/ainize-team/ainize-js) -- [AinModule](https://github.com/ainize-team/ainize-js/blob/main/src/ain.ts) +### Rules and Owners + +[Rule configs](https://docs.ainetwork.ai/ain-blockchain/ai-network-design/blockchain-database/rules-and-owners/rule-configs) validate transactions and control write permissions, while [owner configs](https://docs.ainetwork.ai/ain-blockchain/ai-network-design/blockchain-database/rules-and-owners/owner-configs) manage write access to both rules and themselves. + +The following code shows how to configure a rule to allow write access for all users: + +```js +const Ain = require('@ainblockchain/ain-js').default; + +const ain = new Ain('https://testnet-api.ainetwork.ai', 'wss://testnet-event.ainetwork.ai', 0); -#### [ainft-js](https://github.com/ainize-team/ainize-js) -- [AinftJs](https://github.com/ainft-team/ainft-js/blob/main/src/ainft.ts) +async function main() { + const address = ain.wallet.addAndSetDefaultAccount('YOUR_PRIVATE_KEY'); -## Test How-To -For testing, you need a blockchain node cluster running locally. -1. Clone AIN Blockchain and install + // set the rule to allow write access for all users + const result = await ain.db.ref(appPath).setRule({ + value: { + '.rule': { + write: true, + }, + }, + gas_price: 500, + timestamp: Date.now(), + nonce: -1, + }); +} + +main(); ``` -git clone git@github.com:ainblockchain/ain-blockchain.git -cd ain-blockchain -yarn install + +### Function Call + +```js +const Ain = require('@ainblockchain/ain-js').default; + +const ain = new Ain('https://testnet-api.ainetwork.ai', 'wss://testnet-event.ainetwork.ai', 0); + +async function main() { + const address = ain.wallet.addAndSetDefaultAccount('YOUR_PRIVATE_KEY'); + + // trigger a function when a value is written to the data path + const result = await ain.db.ref('YOUR_DATA_PATH').setFunction({ + value: { + '.function': { + YOUR_FUNCTION_ID: { + function_type: 'REST', + function_url: 'YOUR_FUNCTION_URL', + function_id: 'YOUR_FUNCTION_ID', + }, + }, + }, + gas_price: 500, + timestamp: Date.now(), + nonce: -1, + }); +} + +main(); ``` -2. Start blockchain locally +## Documentation + +Browse the documentation online: + +- [Quick Start](https://docs.ainetwork.ai/ain-blockchain/developer-guide/getting-started) +- [Full API Documentation](https://ainblockchain.github.io/ain-js) +- [Developer Guide](https://docs.ainetwork.ai/ain-blockchain/developer-guide) + +## Testing + +To run tests, a local blockchain node must be running. + +1. Clone and install the AIN Blockchain: + +```sh +$ git clone https://github.com/ainblockchain/ain-blockchain.git +$ cd ain-blockchain +$ npm install ``` -cd ain-blockchain -bash start_local_blockchain.sh + +2. Start the local blockchain: + +```sh +$ bash start_local_blockchain.sh ``` -* Note that the node 2 of the blockchain needs to be started with ENABLE_EVENT_HANDLER=true env variable for the event manager test cases. -3. Run tests +- For event manager test cases, ensure Node 2 is started with the `ENABLE_EVENT_HANDLER` environment variable set to `true`. + +3. Run the tests: + +```sh +$ npm run test ``` -yarn run test -yarn run test_snapshot # update test snapshot files + +- To update test snapshot files: + +```sh +$ npm run test_snapshot ``` -## LICENSE +## License -MPL-2.0 +MPL-2.0 License. From 244fb09ccd33893198eba47d25ced7daa8d5022c Mon Sep 17 00:00:00 2001 From: platfowner Date: Mon, 23 Dec 2024 00:41:25 +0000 Subject: [PATCH 2/2] Upgrade version to 1.13.3 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 161a251..f449b83 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@ainblockchain/ain-js", - "version": "1.13.2", + "version": "1.13.3", "description": "", "main": "lib/ain.js", "scripts": {