From 06bf11c49c8e29456410ff1d40f10b4d09e8db12 Mon Sep 17 00:00:00 2001 From: Pana Date: Mon, 19 Feb 2024 11:29:55 +0800 Subject: [PATCH] Update doc outdated links and add new doc (#251) * update doc links * complete new doc * add example --- README.md | 61 +++++++++++++++++++++++++++++++--- SUMMARY.md | 3 +- docs/FAQs.md | 15 +++++++++ docs/api/README.md | 13 ++++---- docs/how_to_send_tx.md | 2 +- docs/index.md | 44 +++++++++++++++++++----- docs/interact_with_contract.md | 4 +-- docs/overview.md | 10 +++--- docs/providers.md | 2 +- 9 files changed, 124 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 4b11870..2533866 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,20 @@ [![npm](https://img.shields.io/npm/v/js-conflux-sdk.svg)](https://www.npmjs.com/package/js-conflux-sdk) [![npm](https://img.shields.io/npm/dm/js-conflux-sdk.svg)](https://www.npmjs.com/package/js-conflux-sdk) -JavaScript Conflux Software Development Kit is a complete library for interacting with the [Conflux Blockchain Core Space](https://doc.confluxnetwork.org/) in both Node.js and browser environment. +JavaScript Conflux Software Development Kit is a complete library for interacting with the [Conflux Blockchain Core Space](https://doc.confluxnetwork.org/docs/core/Overview) in both Node.js and browser environment. + +Featured with: + +* Full support of Conflux Network Core Space's JSON-RPC API +* Wallet management +* Meta-classes create JavaScript objects from any contract ABI, including ABIv2 and Human-Readable ABI +* Unit(CFX, Drip) conversion +* Common utilities: + 1. Address conversion + 2. ABI/RLP encoding/decoding + 3. Crypto utilities + 4. Type conversion +* Extensive documentation and examples ## Docs @@ -11,9 +24,10 @@ JavaScript Conflux Software Development Kit is a complete library for interactin * [SDK API doc](./docs/api/README.md) * [Examples](./example/README.md) * [Community examples](https://github.com/conflux-fans/js-sdk-example) -* [Fullnode JSONRPC API](https://doc.confluxnetwork.org/docs/core/build/json-rpc/json_rpc) -* [Public RPC endpoints](https://doc.confluxnetwork.org/docs/core/build/sdks-and-tools/conflux_rpcs) +* [Fullnode JSONRPC API](https://doc.confluxnetwork.org/docs/core/build/json-rpc/) +* [Public RPC Provider Endpoints](https://doc.confluxnetwork.org/docs/core/conflux_rpcs) * [Testnet faucet](https://faucet.confluxnetwork.org/) +* [Core Space Documentation](https://doc.confluxnetwork.org/docs/core/Overview) * [FAQs](./docs/FAQs.md) ## Install @@ -75,12 +89,49 @@ or ``` -From `v2.0` the exported class to browser window name changed from Conflux to `TreeGraph` +From `v2.0` the exported root class to browser window name changed from Conflux to `TreeGraph` Or you can use public CDN links: * [`jsdelivr`](https://cdn.jsdelivr.net/npm/js-conflux-sdk/dist/js-conflux-sdk.umd.min.js) +## Quick Start + +After importing the package, you can use the `Conflux` class instance to interact with the Conflux network, such as querying the balance of an account, sending a transaction. + +```javascript +const { Conflux, Drip } = require('js-conflux-sdk'); + +const conflux = new Conflux({ + url: 'https://test.confluxrpc.com', + networkId: 1, // Note: network is required + logger: console, // for debug +}); + +const exampleAddress = 'cfxtest:aar8jzybzv0fhzreav49syxnzut8s0jt1a1pdeeuwb'; + +async function main() { + const balance = await conflux.cfx.getBalance(exampleAddress); + console.log(`Balance of ${exampleAddress} is ${Drip(balance).toCFX()} CFX`); + + const account = await conflux.wallet.addPrivateKey(process.env.PRIVATE_KEY); // prepare and set your private key as environment variable + + const txHash = await conflux.cfx.sendTransaction({ + from: account.address, + to: exampleAddress, + value: Drip.fromCFX(1), // send 1 CFX + }); + + console.log(`Transaction hash: ${txHash}`); + + // after the transaction is executed, you can query the receipt, and the receiver should have 1 CFX more +} + +main().catch(console.error); +``` + +For more guides and examples, please refer to the [SDK documentation](https://docs.confluxnetwork.org/js-conflux-sdk). + ## Address conversion performance To gain an address conversion(hex->base32 or reverse) performance boost, you can install [`@conflux-dev/conflux-address-rust`](https://github.com/conflux-fans/conflux-address-rust-binding) in your project. Which will be used to replace the purejs version and can gain a `10-100` performance boost. @@ -119,5 +170,5 @@ v1.5.11+ | v1.1.1+ ## Related Projects | Tools * [CIP-23](https://github.com/conflux-fans/cip-23) can be used to work with Conflux signTypedData -* [hardhat-conflux](https://github.com/conflux-chain/hardhat-conflux) hardhat plugin that can be used to interact with Conflux Core network +* [hardhat-conflux](https://github.com/conflux-chain/hardhat-conflux) hardhat plugin that can be used to interact with Conflux Core Network Contracts * [@conflux-dev/hdwallet](https://github.com/Conflux-Chain/ts-conflux-sdk/tree/main/packages/hdwallet) HD Wallet diff --git a/SUMMARY.md b/SUMMARY.md index 4812293..d7ce6c9 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,8 +1,8 @@ # Table of contents * [Home](README.md) -* [QuickStart](docs/quick_start.md) * [Introduction](docs/index.md) +* [QuickStart](docs/quick_start.md) * [Overview](docs/overview.md) * [Contrast with web3.js](docs/jssdk-vs-web3.md) * [Guides](docs/README.md) @@ -24,3 +24,4 @@ * [Wallet](docs/api/wallet/Wallet.md) * [Release notes](change_log.md) * [v2.0 Changes](docs/v2.0_changes.md) +* [FAQs](docs/FAQs.md) diff --git a/docs/FAQs.md b/docs/FAQs.md index d41c101..feb346e 100644 --- a/docs/FAQs.md +++ b/docs/FAQs.md @@ -3,3 +3,18 @@ ## Is js-conflux-sdk support mnemonic or HDwallet ? Mnemonic can be support by a third package `@conflux-dev/hdwallet`, check [SDK account doc](./account.md) HD wallet part for detail intro. + +## Common Errors + +Check [Error Handling](./error_handling.md) for common errors and how to handle them. + +## Why is the transaction not mined or sending transaction timeout? + +If you are sending a transaction and it is not mined or it is timeout, you can check the following: + +* The sending account have enough balance. +* If the transaction should be sponsored, the sponsor account have enough balance. +* The transaction nonce is correct(not bigger than sender account's nonce). +* If the network is busy, you can try to increase the gas price. + +For more detail, check [why tx is pending?](https://doc.confluxnetwork.org/docs/core/core-space-basics/transactions/why-transaction-is-pending) and [Transaction lifecycle for more info](https://doc.confluxnetwork.org/docs/core/core-space-basics/transactions/lifecycle) diff --git a/docs/api/README.md b/docs/api/README.md index 431d3eb..46b8c82 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -1,11 +1,10 @@ # API -* [Conflux](./Conflux.md) The `Conflux` class provide methods to interact with RPC and contract. -* [Wallet](./wallet/Wallet.md) -* [PrivateKeyAccount](./wallet/PrivateKeyAccount.md) -* [Transaction](./Transaction.md) +* [Conflux](./Conflux.md) The `Conflux` class provide methods to interact with RPC methods and send transaction. +* [Wallet](./wallet/Wallet.md) The `Wallet` class provide methods to manage accounts and sign transactions. +* [PrivateKeyAccount](./wallet/PrivateKeyAccount.md) The `PrivateKeyAccount` class can be used to sign transactions or messages. It can be created from a private key or be random generated. +* [Transaction](./Transaction.md) The `Transaction` class provide methods to construct and encode transactions. * [Drip](./Drip.md) Drip - CFX converter * [format](./util/format.md) Type formaters -* [sign](./util/sign.md) -* [address utilities](./util/address.md) -* [Provider](./provider/BaseProvider.md) \ No newline at end of file +* [sign](./util/sign.md) Crypto utilities +* [address utilities](./util/address.md) Address utilities \ No newline at end of file diff --git a/docs/how_to_send_tx.md b/docs/how_to_send_tx.md index bcd8479..21a1e82 100644 --- a/docs/how_to_send_tx.md +++ b/docs/how_to_send_tx.md @@ -62,7 +62,7 @@ If the transaction receipt's `outcomeStatus` is `0`, congratulate you have send ### Transaction's stage -After sending, a transaction could be in several different states, [here](https://developer.confluxnetwork.org/sending-tx/en/transaction_stage) is a detail explanation of transaction life cycle. +After sending, a transaction could be in several different states, [here](https://doc.confluxnetwork.org/docs/core/core-space-basics/transactions/lifecycle) is a detail explanation of transaction life cycle. You can get a transaction's state by it's `status` or it's receipt's `outcomeStatus` diff --git a/docs/index.md b/docs/index.md index c5e6d0d..722dd38 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,29 +7,57 @@ It’s commonly found in decentralized apps (dapps) to help with sending transac ## Getting Started * Unfamiliar with Conflux? → [confluxnetwork](http://confluxnetwork.org) -* Unfamiliar with Solidity? → [Solidity documentation](https://docs.soliditylang.org/en/v0.8.10/) -* Ready to code? → [Quickstart](quick_start.md) +* Unfamiliar with Solidity? → [Solidity documentation](https://soliditylang.org/) +* Ready to code? → [QuickStart](quick_start.md) * Interested in a quick tour? → [Overview](overview.md) * Like to give back? → [Contribute](https://github.com/conflux-chain/js-conflux-sdk) * Want to get testnet CFX? → [Conflux testnet faucet](http://faucet.confluxnetwork.org/) +* Conflux sponsorship mechanism? → [Sponsorship](https://doc.confluxnetwork.org/docs/core/core-space-basics/sponsor-mechanism) ## Table of Contents -* [Quickstart](quick_start.md) +* [QuickStart](quick_start.md) * [Overview](overview.md) * [Changelog](../change_log.md) * [js-sdk examples](https://github.com/conflux-fans/js-sdk-example) ## Guides +* [Providers](providers.md) How to connect to Conflux network in different ways. +* [CIP37 Address](conflux_checksum_address.md) How to convert between different address formats. +* [Account](account.md) How to create and manage accounts. +* [Sending Transaction](how_to_send_tx.md) How to send transactions and wait tx confirmed. +* [Interact with Contract](interact_with_contract.md) How to interact with smart contracts. +* [Sign methods](sign_methods.md) How to sign messages and transactions. +* [Error Handling](error_handling.md) How to handle errors. +* [Batch RPC](batch_rpc.md) How to batch RPC requests. + +## Examples + +* [`Conflux` class initialization](https://github.com/Conflux-Chain/js-conflux-sdk/blob/v2/example/0_create_conflux.js) +* [Account and balance](https://github.com/Conflux-Chain/js-conflux-sdk/blob/v2/example/1_account_and_balance.js) +* [Send transaction](https://github.com/Conflux-Chain/js-conflux-sdk/blob/v2/example/2_send_transaction.js) +* [Epoch, Block, Transaction](https://github.com/Conflux-Chain/js-conflux-sdk/blob/v2/example/3_epoch_block_transaction.js) +* [Contract deploy and interact](https://github.com/Conflux-Chain/js-conflux-sdk/blob/v2/example/4_contract_deploy_and_call.js) +* [Contract override](https://github.com/Conflux-Chain/js-conflux-sdk/blob/v2/example/5_contract_override.js) + +Check more community examples in [js-sdk-example](https://github.com/conflux-fans/js-sdk-example) + ## API -* [API](api.md) +* [Conflux](./api/Conflux.md) The `Conflux` class provide methods to interact with RPC methods and send transaction. +* [Wallet](./api/wallet/Wallet.md) The `Wallet` class provide methods to manage accounts and sign transactions. +* [PrivateKeyAccount](./api/wallet/PrivateKeyAccount.md) The `PrivateKeyAccount` class can be used to sign transactions or messages. It can be created from a private key or be random generated. +* [Transaction](./api/Transaction.md) The `Transaction` class provide methods to construct and encode transactions. +* [Drip](./api/Drip.md) Drip - CFX converter +* [format](./api/util/format.md) Type formaters +* [sign](./api/util/sign.md) Crypto utilities +* [address utilities](./api/util/address.md) Address utilities ## Other Docs -1. [Official developer documentation](https://developer.confluxnetwork.org/) -2. [RPC](https://developer.confluxnetwork.org/conflux-doc/docs/json_rpc) -3. [Subscribtion](https://developer.confluxnetwork.org/conflux-doc/docs/pubsub) -4. [FluentWallet](https://fluentwallet.com/) +1. [Official developer documentation](https://doc.confluxnetwork.org/) +2. [RPC API](https://doc.confluxnetwork.org/docs/core/build/json-rpc/) +3. [Subscription](https://doc.confluxnetwork.org/docs/core/build/json-rpc/pubsub) +4. [FluentWallet Official Site](https://fluentwallet.com/) 5. [Fluent documentation](https://fluent-wallet.zendesk.com/hc/en-001) diff --git a/docs/interact_with_contract.md b/docs/interact_with_contract.md index 177b34a..98faab4 100644 --- a/docs/interact_with_contract.md +++ b/docs/interact_with_contract.md @@ -97,7 +97,7 @@ main(); ## How to play with InternalContract -Conflux network has provide Internal Contracts `AdminControl`, `SponsorWhitelistControl`, `Staking`, these internal contract are very helpful to contract developer, for detail documentation check [official doc](https://developer.confluxnetwork.org/conflux-rust/internal_contract/internal_contract). This SDK have fully support for Internal Contract, you can use them like this. +Conflux network has provide Internal Contracts `AdminControl`, `SponsorWhitelistControl`, `Staking`, these internal contract are very helpful to contract developer, for detail documentation check [official doc](https://doc.confluxnetwork.org/docs/core/core-space-basics/internal-contracts/). This SDK have fully support for Internal Contract, you can use them like this. ```javascript const { Conflux } = require('js-conflux-sdk'); @@ -155,7 +155,7 @@ console.log(receipt.logs); ### Get log with `cfx_getLogs` method -Also there is an RPC [`cfx_getLogs`](https://developer.confluxnetwork.org/conflux-doc/docs/json_rpc#cfx_getlogs) to get logs. An filter object is need to invoke this method. +Also there is an RPC [`cfx_getLogs`](https://doc.confluxnetwork.org/docs/core/build/json-rpc/cfx-namespace#cfx_getlogs) to get logs. An filter object is need to invoke this method. ```js let logs = await conflux.cfx.getLogs({ diff --git a/docs/overview.md b/docs/overview.md index 7b9c1fc..32157dc 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -10,7 +10,7 @@ The purpose of this page is to give you a sense of everything js-conflux-sdk can ## Initialize -After installing `js-conflux-sdk` (via npm), you’ll need to specify the provider url. You can use the mainnet([https://main.confluxrpc.com](https://main.confluxrpc.com)), or testnet([https://test.confluxrpc.com](https://test.confluxrpc.com)), or [run your own Conflux node](https://developer.confluxnetwork.org/conflux-doc/docs/independent_chain). +After installing `js-conflux-sdk` (via npm), you’ll need to specify the provider url. You can use the mainnet([https://main.confluxrpc.com](https://main.confluxrpc.com)), or testnet([https://test.confluxrpc.com](https://test.confluxrpc.com)), or [run your own Conflux node](https://doc.confluxnetwork.org/docs/general/run-a-node/Overview). ### Testnet @@ -49,7 +49,7 @@ conflux.wallet.addPrivateKey('0x0123456789abcdef0123456789abcdef0123456789abcdef ### Send JSON-RPC request -There are a lot methods on cfx object which are one-to-one with [Conflux node RPC methods](https://developer.confluxnetwork.org/conflux-doc/docs/json_rpc). All conflux methods will return a promise, so you can use it with `async/await` syntax. +There are a lot methods on cfx object which are one-to-one with [Conflux node RPC methods](https://doc.confluxnetwork.org/docs/core/build/json-rpc/cfx-namespace). All conflux methods will return a promise, so you can use it with `async/await` syntax. ```javascript async function main() { @@ -61,7 +61,7 @@ async function main() { main(); ``` -Besides balance you can get a lot blockchain information through it, for example: nonce, block, transaction, receipt and so on. You can check [API](https://github.com/Conflux-Chain/js-conflux-sdk/tree/faec50e6c2dd16158b114d0d4de228d7b2ca7535/api.md) and [RPC](https://developer.confluxnetwork.org/conflux-doc/docs/json_rpc) +Besides balance you can get a lot blockchain information through it, for example: nonce, block, transaction, receipt and so on. You can check [API](https://github.com/Conflux-Chain/js-conflux-sdk/tree/faec50e6c2dd16158b114d0d4de228d7b2ca7535/api.md) and [RPC](https://doc.confluxnetwork.org/docs/core/build/json-rpc/cfx-namespace) ### Conflux hex address @@ -104,7 +104,7 @@ Check [here](how_to_send_tx.md) for details ### Hex value and epochNumber and tags -You can find the epochNumber doc at official developer [RPC doc](https://developer.confluxnetwork.org/conflux-doc/docs/json_rpc#hex-value-encoding) +You can find the epochNumber doc at official developer [RPC doc](https://doc.confluxnetwork.org/docs/core/build/json-rpc/cfx-namespace#hex-value-encoding) ### JSBI @@ -170,7 +170,7 @@ main(); ### Pub/Sub -Conflux node support pub/sub makes it possible to query certain items on an ongoing basis, without polling through the JSON-RPC HTTP interface, currently three topics are supported: `newHeads`, `epochs`, `logs`, for detail explain of Pub/Sub check the [official doc](https://developer.confluxnetwork.org/conflux-doc/docs/pubsub) +Conflux node support pub/sub makes it possible to query certain items on an ongoing basis, without polling through the JSON-RPC HTTP interface, currently three topics are supported: `newHeads`, `epochs`, `logs`, for detail explain of Pub/Sub check the [official doc](https://doc.confluxnetwork.org/docs/core/build/json-rpc/pubsub) Use JS SDK it will be very easy to use Pub/Sub. diff --git a/docs/providers.md b/docs/providers.md index b522a48..1f810a1 100644 --- a/docs/providers.md +++ b/docs/providers.md @@ -9,7 +9,7 @@ Most nodes have a variety of ways to connect to them. The most common ways to co - Websockets (works remotely, faster than HTTP) - HTTP (more nodes support it) -Currently, js-conflux-sdk has support for both `HTTP` and `Websockets`. Normally, websockets is recommended than HTTP, because it's faster and can use [Pub/Sub methods](https://developer.confluxnetwork.org/conflux-doc/docs/pubsub). If you want to use the PubSub API, websocket provider is the only choice. Conflux-rust's HTTP default port is `12537`, websocket default port is `12535`. They can be changed through [config file](https://developer.confluxnetwork.org/apis/en/node_config_example). +Currently, js-conflux-sdk has support for both `HTTP` and `Websockets`. Normally, websockets is recommended than HTTP, because it's faster and can use [Pub/Sub methods](https://doc.confluxnetwork.org/docs/core/build/json-rpc/pubsub). If you want to use the PubSub API, websocket provider is the only choice. Conflux-rust's HTTP default port is `12537`, websocket default port is `12535`. They can be changed through [config file](https://doc.confluxnetwork.org/docs/general/run-a-node/advanced-topics/node-configuration). When initialize a Conflux object, the underline provider can be configured through the `url` option. If you want to use HTTP provider, then provide an HTTP URL: