Since the launch of Kaia Blockchain this repository has been parked in favour of the new open-source projects in Kaia's Github. Contributors have now moved there continuing with massive open-source contributions to our blockchain ecosystem. Please visit the new repository at kaia/caver-js to continue contributing and to access the latest updates. A big thank you to everyone who has contributed to this repository. For more information about Klaytn's chain merge with Finschia blockchain please refer to the launching of Kaia blockchain - kaia.io.
caver-js is a JavaScript API library that allows developers to interact with a Klaytn node using a HTTP or Websocket connection.
NOTE Kaikas Web Extension Wallet is recommended to be used with features prior to common architecture. New features provided in caver-js v1.5.0 (introduced common architecrue) or later are currently not compatible with Kaikas. Kaikas web extension wallet works fine with functions prior to common architecture, so please use functions prior to common architecture. Even in the latest version of caver-js, functions prior to common architecture are provided for backward compatibility. See Trouble shooting and known issues for more details.
- Requirements
- Installation
- Getting Started
- Documentation
- API Specification
- Web3.js Similarity
- Error Code Improvement
- Sample Projects
- Github Repository
- Trouble shooting and known issues
- Related Projects
The following packages are required to use the caver-js library.
Testing in caver-js is implemented using the mocha testing framework. If you want to run unit tests in caver-js, you need to install mocha first.
Note caver-js can run on Node.js versions 12 and 14, and the recommended versions are:
If you are already using a different version of the node(for example, node v15), use the Node Version Manager(NVM) to install and use the version supported by caver-js.
To try it out, install caver-js with npm like following command:
$ npm install caver-js
Note package.json file should exist on the same install path. If it
does not exist, package.json should be generated via npm init.
To install a specific version of caver-js, try the following command:
$ npm install [email protected]
Build using the caver-js repository:
$ npm run build
Then include dist/caver.min.js in your html file. This will expose Caver on the window object.
Or via CDN:
<script src="https://cdnjs.cloudflare.com/ajax/libs/caver-js/x.x.x/caver.min.js"></script>
The caver-js provided by cdnjs can be found at this link.
If you want to run your own EN (Endpoint Node), see EN Operation Guide to set up. You can connect EN like below:
$ node
> const Caver = require('caver-js')
> const caver = new Caver('http://localhost:8551/')
Note The above example should be executed from the location where caver-js is installed, and the example is explained using Node.js REPL.
You can now use caver-js. You can send a basic request to the node as shown below and check the results.
> caver.rpc.klay.getClientVersion().then(console.log)
Klaytn/vX.X.X/linux-amd64/goX.X.X
You can easily use your Klaytn account when signing a transaction or message by using the Keyring / wallet.
The keyring is a new feature that contains an address and one or more private keys based on the key types (SingleKeyring, MultipleKeyring or RoleBasedKeyring). Refer to caver.wallet.keyring for details. caver.wallet, the in-memory wallet, is provided to easily manage multiple keyrings.
Note Functions associated with wallet and keyring have no effect on the Klaytn blockchain platform. It just manipulates keyrings in the in-memory wallet.
Let's create a random keyring as shown in the example below:
> const keyring = caver.wallet.keyring.generate()
> keyring
SingleKeyring {
_address: '0x64d221893cc628605314026f4c4e0879af5b75b1',
_key: PrivateKey { _privateKey: '0x{private key}' }
}
You can add the keyring object created in the above example to the caver.wallet, or you can add a keyring using an address and private key(s).
// Add a keyring instance to caver.wallet
> caver.wallet.add(keyring)
// Add a keyring to caver.wallet with an address and a private key
> caver.wallet.newKeyring('0x{address in hex}', '0x{private key}')
// Add a keyring to caver.wallet with an address and private keys
> caver.wallet.newKeyring('0x{address in hex}', ['0x{private key1}', '0x{private key2}', ...])
// Add a keyring to caver.wallet with an address and private keys by roles
> caver.wallet.newKeyring('0x{address in hex}', [ ['0x{private key1}', ...], ['0x{private key2}', ...], ['0x{private key3}', ...] ])
You can use caver-js to submit various types of transactions to a node. Please refer to the caver.transaction to see how to create a transaction of each type.
Note you should create a transaction instance via create function. From caver-js v1.8.2, constructors per transaction type are not supported.
You can sign the transaction using a keyring and send a signed transaction through caver.rpc.klay.sendRawTransaction as shown below, and the receipt is returned as a result.
// Add a keyring to caver.wallet
> const keyring = caver.wallet.newKeyring('0x{address in hex}', '0x{private key}')
> const vt = caver.transaction.valueTransfer.create({
from: keyring.address,
to: '0x176ff0344de49c04be577a3512b6991507647f72',
value: caver.utils.convertToPeb(1, 'KLAY'),
gas: 25000,
})
> caver.wallet.sign(keyring.address, vt).then(signed => {
caver.rpc.klay.sendRawTransaction(signed).then(console.log)
})
{
blockHash: '0x0a78b5c5b95456b2d6b6a9ba25fd2afd0000d16bcf03a8ae58a6557a59319a67',
blockNumber: 8021,
contractAddress: null,
from: '0x09a08f2289d3eb3499868908f1c84fd9523fe11b',
...
type: 'TxTypeValueTransfer',
typeInt: 8,
value: '0xde0b6b3a7640000'
}
The above example uses Promise when sending a signed transaction to the Klaytn. You can also use event emitter like below.
caver.rpc.klay.sendRawTransaction(signed).on('transactionHash', function(hash){
...
}).on('receipt', function(receipt){
...
})
Units of KLAY is shown as below, and peb is the smallest currency unit.
peb is the default unit unless the unit conversion is used.
| Name | Unit |
|---|---|
| peb | 1 |
| kpeb | 1,000 |
| Mpeb | 1,000,000 |
| Gpeb | 1,000,000,000 |
| ston | 1,000,000,000 |
| uKLAY | 1,000,000,000,000 |
| mKLAY | 1,000,000,000,000,000 |
| KLAY | 1,000,000,000,000,000,000 |
| kKLAY | 1,000,000,000,000,000,000,000 |
| MKLAY | 1,000,000,000,000,000,000,000,000 |
| GKLAY | 1,000,000,000,000,000,000,000,000,000 |
| TKLAY | 1,000,000,000,000,000,000,000,000,000,000 |
caver-js provides the caver.utils.convertToPeb function for unit conversion. Please refer to the usage below.
> caver.utils.convertToPeb(1, 'peb')
'1'
> caver.utils.convertToPeb(1, 'Gpeb')
'1000000000'
> caver.utils.convertToPeb(1, 'KLAY')
'1000000000000000000'
Documentation can be found at Klaytn Docs-caver-js.
The API lists of caver-js are described in folloinwg links:
- caver.account
- caver.wallet
- caver.wallet.keyring
- caver.transaction
- caver.rpc.klay
- caver.rpc.net
- caver.contract
- caver.abi
- caver.kct.kip7
- caver.kct.kip17
- caver.utils
- caver.ipfs
Since caver-js has been evolved from web3.js, usage pattern of caver-js is very similar to that of web3.js. This means a software developed using web3.js can be easily converted to caver-js. The following examples are code patterns used in web3.js and caver-js, respectively.
const Web3 = require('web3');
const web3 = new Web3(new web3.providers.HttpProvider('http://localhost:8545'));
web3.eth.getBalance('0x407d73d8a49eeb85d32cf465507dd71d507100c1').then(console.log)
const Caver = require('caver-js');
const caver = new Caver(new Caver.providers.HttpProvider('http://localhost:8545'));
caver.rpc.klay.getBalance('0x407d73d8a49eeb85d32cf465507dd71d507100c1').then(console.log)
Klaytn improves reporting transaction failure via txError in the receipt. caver-js further improves the report by presenting the error string that corresponds to txError.
The below is an example of a receipt containing txError.
Error: VM error occurs while running smart contract
{
"blockHash": "0xe7ec35c9fff1178d52cee1d46d40627d19f828c4b06ad1a5c3807698b99acb20",
...
"txError": "0x2",
...
}
The meaning of error code can be found below:
| Error Code | Description |
|---|---|
| 0x02 | VM error occurs while running smart contract |
| 0x03 | max call depth exceeded |
| 0x04 | contract address collision |
| 0x05 | contract creation code storage out of gas |
| 0x06 | evm: max code size exceeded |
| 0x07 | out of gas |
| 0x08 | evm: write protection |
| 0x09 | evm: execution reverted |
| 0x0a | reached the opcode computation cost limit (100000000) for tx |
| 0x0b | account already exists |
| 0x0c | not a program account (e.g., an account having code and storage) |
| 0x0d | Human-readable address is not supported now |
| 0x0e | fee ratio is out of range [1, 99] |
| 0x0f | AccountKeyFail is not updatable |
| 0x10 | different account key type |
| 0x11 | AccountKeyNil cannot be initialized to an account |
| 0x12 | public key is not on curve |
| 0x13 | key weight is zero |
| 0x14 | key is not serializable |
| 0x15 | duplicated key |
| 0x16 | weighted sum overflow |
| 0x17 | unsatisfiable threshold. Weighted sum of keys is less than the threshold. |
| 0x18 | length is zero |
| 0x19 | length too long |
| 0x1a | nested composite type |
| 0x1b | a legacy transaction must be with a legacy account key |
| 0x1c | deprecated feature |
| 0x1d | not supported |
| 0x1e | smart contract code format is invalid |
The BApp (Blockchain Application) Development sample projects using caver-js are the following:
Kaikas Web Extension Wallet works normally with functions prior to common architecture. Features provided in later versions (caver-js v1.5.0~) may not work with Kaikas Web Extension Wallet.
If the following error occurs when using with Kaikas, it must be modified to use the functions supported by caver-js v1.4.1. For compatibility with the latest version, the same functions provided by caver-js v1.4.0 are provided.
Kaikas only processes one transaction at a time. Open Kaikas and refresh the pending transaction. If the service doesn’t process your transaction for a while, cancel the pending transaction.
Kaikas는 한 번에 하나의 트랜잭션만 처리합니다. Kaikas를 열어 대기 중인 트랜잭션을 새로고침 해주세요. 만약 대기 상태가 계속된다면 이용 중인 서비스가 트랜잭션을 처리하지 않는 것이니 트랜잭션을 취소바랍니다.
Although the above error is mostly the case, other errors may occur besides the above error, so if you are using Kaikas Web Extension Wallet, please use the functions supported by caver-js v1.4.1. Keep in mind that you cannot mix features before and after common architecture.
For documents for the functions supported by caver-js v1.4.1, refer to caver-js ~v1.4.1 Documentation.
Node.js module polyfills are not provided by default in webpack v5 and later.
Therefore, you need to install the missing modules and add them to the resolve.fallback property of the webpack.config.js file in the form below.
module.exports = {
...
resolve: {
fallback: {
fs: false,
net: false,
stream: require.resolve('stream-browserify'),
crypto: require.resolve('crypto-browserify'),
http: require.resolve('stream-http'),
https: require.resolve('https-browserify'),
os: require.resolve('os-browserify/browser'),
...
},
},
}
More information on migrating to webpack v5 can be found here.
If you are implementing an app using create-react-app, you can use react-app-rewired to add the above polyfills to the webpack.config.js file used by CRA. More information on using react-app-rewired with create-react-app can be found here.
caver-java for Java