ICON supports JavaScript SDK for 3rd party or user services development. You can integrate ICON JavaScript SDK into your project and utilize ICON’s functionality. This document provides you with an information of installation and API specification.
- Installation
- API Specification - Introduction
- IconService
- IconService.IconWallet
- IconService.IconBuilder
- IconService.IconBuilder.IcxTransactionBuilder
- IconService.IconBuilder.MessageTransactionBuilder
- IconService.IconBuilder.DeployTransactionBuilder
- IconService.IconBuilder.CallTransactionBuilder
- IconService.IconBuilder.DepositTransactionBuilder
- IconService.IconBuilder.CallBuilder
- IconService.SignedTransaction
- IconService.HttpProvider
- IconService.IconAmount
- IconService.IconConverter
- IconService.IconHexadecimal
- IconService.IconValidator
- Error cases
- References
Install icon-sdk-js
module using npm
.
npm install --save icon-sdk-js
Import icon-sdk-js
module.
const IconService = require('icon-sdk-js');
Install icon-sdk-js
module using npm
,
npm install --save icon-sdk-js
or using CDN.
<script src="https://cdn.jsdelivr.net/npm/icon-sdk-js@latest/build/icon-sdk-js.web.min.js"></script>
Then, import icon-sdk-js
module.
import IconService from 'icon-sdk-js';
Install icon-sdk-js
module using npm
,
npm install --save icon-sdk-js
Then, import icon-sdk-js/build/icon-sdk-js.web.min.js
module.
import IconService from 'icon-sdk-js/build/icon-sdk-js.web.min.js';
IconService
is a root class of icon-sdk-js
, which provides APIs to communicate with ICON nodes and contains different type of modules. Details of modules are as below:
Module | Description |
---|---|
IconService | Class which provides APIs to communicate with ICON nodes |
IconService.IconWallet | Class which provides EOA functions. |
IconService.IconBuilder | Builder class for transaction object. |
IconService.SignedTransaction | Class representing the signed transaction object. |
IconService.HttpProvider | Class representing HTTP-based provider |
IconService.IconAmount | Class which provides unit conversion functions. |
IconService.IconConverter | Util module contains conversion functions. |
IconService.IconHexadecimal | Util module contains hex-prefix functions. |
IconService.IconValidator | Util module contains validator functions. |
IconService
is a class which provides APIs to communicate with ICON nodes. It enables you to easily use ICON JSON-RPC APIs (version 3). All instance methods of IconService
returns a HttpCall
instance. To execute the request and get the result value, you need to run execute()
function of HttpCall
instance. All requests will be executed asynchronously. Synchronous request is not available.
Creates an instance of IconService.
new IconService(provider: HttpProvider)
Parameter | Type | Description |
---|---|---|
provider | HttpProvider |
HttpProvider instance. |
const httpProvider = new HttpProvider('https://ctz.solidwallet.io/api/v3');
const iconService = new IconService(httpProvider);
Get the total number of issued coins.
.getTotalSupply() => HttpCall // .execute() => BigNumber
None
HttpCall
- The HttpCall instance for icx_getTotalSupply
JSON-RPC API request. If execute()
successfully, it returns a BigNumber
value of total issued coins.
/* Returns the total number of issued coins. */
const totalSupply = await iconService.getTotalSupply().execute();
Get the balance of the address.
.getBalance(address: string) => HttpCall // .execute() => BigNumber
Parameter | Type | Description |
---|---|---|
address | string |
an EOA address. |
HttpCall
- The HttpCall instance for icx_getBalance
JSON-RPC API request. If execute()
successfully, it returns a BigNumber
value of ICX balance.
/* Returns the balance of a EOA address */
const balance = await iconService.getBalance('hx9d8a8376e7db9f00478feb9a46f44f0d051aab57').execute();
Get the block information.
Since this API is an old version, we recommend to use getBlockByHeight(), getBlockByHash(), getLastBlock() API.
.getBlock(value: string|number|BigNumber) => HttpCall // .execute() => object
Parameter | Type | Description |
---|---|---|
value | string , number , BigNumber |
the height or hash value of block. |
Depending on the type of input value, there are different ways to get block information.
-
Get block by height - Put integer value of a block height. It will delegate to icx_getBlockByHeight RPC method.
-
Get block by hash - Put block hash value. It will delegate to icx_getBlockByHash RPC method.
-
Get latest block - Put the string
'latest'
. It will delegate to icx_getLastBlock RPC method.
HttpCall
- The HttpCall instance for icx_getBlockByHeight
, icx_getBlockByHash
or icx_getLastBlock
JSON-RPC API request. If execute()
successfully, it returns a block object
. For details of returned block object, see Example section of icx_getLastBlock.
// Returns block information by block height
const block1 = await iconService.getBlock(1000).execute();
// Returns block information by block hash
const block2 = await iconService.getBlock("0xdb310dd653b2573fd673ccc7489477a0b697333f77b3cb34a940db67b994fd95").execute();
// Returns latest block information
const block2 = await iconService.getBlock("latest").execute();
Get the block information by block height.
.getBlockByHeight(value: number|BigNumber) => HttpCall // .execute() => object
Parameter | Type | Description |
---|---|---|
value | number , BigNumber |
the height value of block. |
HttpCall
- The HttpCall instance for icx_getBlockByHeight
JSON-RPC API request. If execute()
successfully, it returns a block object
.
// Returns block information
const block = await iconService.getBlockByHeight(1000).execute();
Get the block information by block hash.
.getBlockByHash(value: string) => HttpCall // .execute() => object
Parameter | Type | Description |
---|---|---|
value | string |
a block hash. |
HttpCall
- The HttpCall instance for icx_getBlockByHash
JSON-RPC API request. If execute()
successfully, it returns a block object
.
// Returns block information
const block = await iconService.getBlockByHash('0xdb310dd653b2573fd673ccc7489477a0b697333f77b3cb34a940db67b994fd95').execute();
Get the latest block information.
.getLastBlock() => HttpCall // .execute() => object
None
HttpCall
- The HttpCall instance for icx_getLastBlock
JSON-RPC API request. If execute()
successfully, it returns a block object
.
// Returns block information
const block = await iconService.getLastBlock().execute();
Get the SCORE API list.
.getScoreApi(address: string) => HttpCall // .execute() => array
Parameter | Type | Description |
---|---|---|
address | string |
a SCORE address. |
HttpCall
- The HttpCall instance for icx_getScoreApi
JSON-RPC API request. If execute()
successfully, it returns a ScoreApiList
instance, the API list of SCORE address.
ScoreApiList
provides two instance methods, getList()
and getMethod()
.
-
getList() - Returns
array
of API list. -
getMethod(method:
string
) - Returnsobject
of method information.
// Returns the SCORE API list
const apiList = await iconService.getScoreApi('cx0000000000000000000000000000000000000001').execute();
// [ { type: 'function', name: 'acceptScore', inputs: [ [Object] ] outputs: [] }, ··· { type: 'eventlog', name: 'UpdateServiceConfigLog', inputs: [ [Object] ] }]
console.log(apiList.getList());
// { type: 'function', name: 'getStepCosts', inputs: [], outputs: [ { type: 'dict' } ], readonly: '0x1' }
console.log(apiList.getMethod('getStepCosts'));
Get the transaction information.
.getTransaction(hash: string) => HttpCall // .execute() => object
Parameter | Type | Description |
---|---|---|
hash | string |
a transaction hash. |
HttpCall
- The HttpCall instance for icx_getTransactionByHash
JSON-RPC API request. If execute()
successfully, it returns a transaction object
. For details of returned object, see here.
// Returns the transaction object.
const txObject = await iconService.getTransaction('0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238').execute();
Get the result of transaction by transaction hash.
.getTransactionResult(hash: string) => HttpCall // .execute() => object
Parameter | Type | Description |
---|---|---|
hash | string |
a transaction hash. |
HttpCall
- The HttpCall instance for icx_getTransactionResult
JSON-RPC API request. If execute()
successfully, it returns a transaction result object
. For details of returned object, see here.
// Returns the transaction result object.
const txObject = await iconService.getTransactionResult('0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238').execute();
Get the transaction trace. newly added from ICON2
.getTrace(hash: string) => HttpCall // .execute() => any
Parameter | Type | Description |
---|---|---|
hash | string |
HttpCall
- The HttpCall instance for debug_getTrace
JSON-RPC API request. If execute()
successfully, it returns a BigNumber
value of estimated step.
// Returns the transaction trace.
const trace = await iconService.getTrace(hash).execute();
Send a transaction that changes the states of address.
.sendTransaction(signedTransaction: SignedTransaction) => HttpCall // .execute() => string
Parameter | Type | Description |
---|---|---|
signedTransaction | SignedTransaction |
an instance of SignedTransaction class. |
HttpCall
- The HttpCall instance for icx_sendTransaction
JSON-RPC API request. If execute()
successfully, it returns a string
value of transaction hash.
// Returns the tx hash of transaction.
const txHash = await iconService.sendTransaction(signedTransaction).execute();
Returns an estimated step of how much step is necessary to allow the transaction to complete.
.estimateStep(transaction:IcxTransaction | MessageTransaction | DepositTransaction | DeployTransaction | CallTransaction) => HttpCall // .execute() => string
Parameter | Type | Description |
---|---|---|
transaction | IcxTransaction |
an instance of [IcxTransaction |
HttpCall
- The HttpCall instance for debug_estimateStep
JSON-RPC API request. If execute()
successfully, it returns a BigNumber
value of estimated step.
// Returns the estimated step to execute transaction.
const step = await iconService.estimateStep(transaction).execute();
It sends a transaction like icx_sendTransaction
, then it will wait for the
result.
sendTransactionAndWait(signedTransaction: SignedTransaction) => HttpCall // .execute() => object
Parameter | Type | Description |
---|---|---|
signedTransaction | SignedTransaction |
an instance of SignedTransaction class. |
HttpCall
- The HttpCall instance for icx_sendTransactionAndWait
JSON-RPC API request. If execute()
successfully, it returns a object
value of transaction result.
// Returns the tx hash of transaction.
const result = await iconService.sendTransactionAndWait(signedTransaction).execute();
It will wait for the result of the transaction for specified time.
waitTransactionResult(hash: string) => HttpCall // .execute() => object
Parameter | Type | Description |
---|---|---|
hash | string |
transaction hash |
HttpCall
- The HttpCall instance for icx_waitTransactionResult
JSON-RPC API request. If execute()
successfully, it returns a transaction result object
. For details of returned object, see here.
// Returns the tx hash of transaction.
const result = await iconService.waitTransactionResult(hash).execute();
Get data by hash.
It can be used to retrieve data based on the hash algorithm (SHA3-256).
Following data can be retrieved by a hash.
- BlockHeader with the hash of the block
- Validators with BlockHeader.NextValidatorsHash
- Votes with BlockHeader.VotesHash
- etc…
getDataByHash(hash: string) => HttpCall // .execute() => string
Parameter | Type | Description |
---|---|---|
hash | string |
The hash value of the data to retrieve |
HttpCall
- The HttpCall instance for icx_getDataByHash
JSON-RPC API request. If execute()
successfully, it returns base64 encoded data
// Returns the tx hash of transaction.
const data = await iconService.getDataByHash(hash).execute();
Get block header for specified height.
getBlockHeaderByHeight(height: string | BigNumber) => HttpCall // .execute() => string
Parameter | Type | Description |
---|---|---|
height | `string | BigNumber` |
HttpCall
- The HttpCall instance for icx_getBlockHeaderByHeight
JSON-RPC API request. If execute()
successfully, it returns base64 encoded data
// Returns the tx hash of transaction.
const data = await iconService.getBlockHeaderByHeight(height).execute();
Get votes for the block specified by height.
getVotesByHeight(height: string | BigNumber) => HttpCall // .execute() => string
Parameter | Type | Description |
---|---|---|
height | `string | BigNumber` |
HttpCall
- The HttpCall instance for icx_getVotesByHeight
JSON-RPC API request. If execute()
successfully, it returns base64 encoded votes data
// Returns the tx hash of transaction.
const data = await iconService.getVotesByHeight(height).execute();
Get proof for the receipt. Proof, itself, may include the receipt.
getProofForResult(hash: string | BigNumber, index: string | BigNumber) => HttpCall // .execute() => Array<string>
Parameter | Type | Description |
---|---|---|
hash | string |
The hash value of the block including the result. |
index | `string | BigNumber` |
HttpCall
- The HttpCall instance for icx_getProofForResult
JSON-RPC API request. If execute()
successfully, it returns List of base64 encoded proof including the receipt
// Returns the tx hash of transaction.
const data = await iconService.getProofForResult(hash, index).execute();
Get proof for the receipt and the events in it. The proof may include the data itself.
getProofForEvents(hash: string | BigNumber, index: string | BigNumber, events: Array<string | BigNumber>) => HttpCall // .execute() => Array<string>
Parameter | Type | Description |
---|---|---|
hash | string |
The hash value of the block including the result. |
index | `string | BigNumber` |
events | Array | false |
HttpCall
- The HttpCall instance for icx_getProofForEvents
JSON-RPC API request. If execute()
successfully, it returns List of List of base64 encoded proof including the receipt and the events
// Returns the tx hash of transaction.
const data = await iconService.getProofForEvents(hash, index, events).execute();
Calls external function of SCORE.
.call(call: Call) => HttpCall // .execute() => any
Parameter | Type | Description |
---|---|---|
call | Call |
an instance of Call class builded by CallBuilder. |
HttpCall
- The HttpCall instance for icx_call
JSON-RPC API request. If execute()
successfully, it returns a any
type of value returned by the executed SCORE function.
// Returns the value returned by the executed SCORE function.
const result = await iconService.call(call).execute();
IconWallet
is a class which provides EOA functions. It enables you to create, load, and store Wallet
object.
Creates an instance of Wallet
class. To create wallet, please use create()
static function instead of instantiating this class directly.
new Wallet(privKey: string, pubKey: string)
Parameter | Type | Description |
---|---|---|
privKey | string |
a private key. |
pubKey | string |
a public key. |
Creates an instance of Wallet
class.
IconWallet.create() => Wallet
None
Wallet
- Wallet instance. It contains a public key and a private key randomly generated by create()
function.
// Creates an instance of Wallet.
const wallet = IconWallet.create();
Import existing wallet using private key.
IconWallet.loadPrivateKey(privKey: string) => Wallet
Parameter | Type | Description |
---|---|---|
privKey | string |
a private key. |
Wallet
- a Wallet instance.
// Load wallet object
const wallet = IconWallet.loadPrivateKey('2ab···e4c');
Import existing wallet using keystore object.
IconWallet.loadKeystore(keystore: object|string, password: string, nonStrict?: boolean) => Wallet
Parameter | Type | Description |
---|---|---|
keystore | object , string |
the keystore object (or stringified object.) |
password | string |
the password of keystore object. |
nonStrict (optional) | boolean |
set whether checking keystore file case-insensitive or not. (affects when keystore param is string.) |
Wallet
- a Wallet instance.
const testKeystore = { "version": 3, "id": "41fc1ddb-4faf-4c88-b494-8fe82a4bab63", "address": "hxd008c05cbc0e689f04a5bb729a66b42377a9a497", "crypto": { "ciphertext": "c4046f5a735403a963110d24f39120a102ad7bc462bf2a14ae334ba4a8c485f6", "cipherparams": { "iv": "441b5a5de3dd33de6f7838b6075702d2" }, "cipher": "aes-128-ctr", "kdf": "scrypt", "kdfparams": { "dklen": 32, "salt": "39d45ffead82d554e35a55efcc7a1f64afe73e9a8ab6b750d959f904e32294ba", "n": 16384, "r": 8, "p": 1 }, "mac": "9bca1f2e8750efb27b7357e1a6a727c596cb812f7a4c45792494a8b0890774d7" }, "coinType": "icx" }
const testPassword = 'qwer1234!'
// Load wallet object
const wallet = IconWallet.loadKeystore(testKeystore, testPassword)
Get keystore object of an instance of a Wallet
class.
.store(password: string, opts?: object) => object
Parameter | Type | Description |
---|---|---|
password | string |
a new password for encryption. |
opts (optional) | object |
the custom options for encryption. |
object
- a keystore object.
const wallet = IconWallet.create()
// Get keystore object of an instance of a `Wallet` class.
const keystore = wallet.store("qwer1234!")
Generate signature string by signing transaction object.
.sign(data: Buffer) => string
Parameter | Type | Description |
---|---|---|
data | Buffer |
the serialized transaction object. |
string
- a signature string.
const wallet = IconWallet.create()
// Get keystore object of an instance of a `Wallet` class.
const signature = wallet.sign('ba4···f64')
Get a private key of Wallet
instance.
.getPrivateKey() => string
None
string
- a private key.
const wallet = IconWallet.create()
// Get private key of `Wallet` instance.
const pk = wallet.getPrivateKey()
Get a public key of Wallet
instance.
.getPublicKey() => string
None
string
- a public key.
const wallet = IconWallet.create()
// Get public key of `Wallet` instance.
const pk = wallet.getPublicKey()
Get an address of Wallet
instance.
.getAddress() => string
None
string
- an EOA address.
const wallet = IconWallet.create()
// Get address of `Wallet` instance.
const pk = wallet.getAddress()
IconBuilder
is an object containing builder class for transaction object. Builder class enables you to make transaction object easily. There are 5 types of builder class as follows:
Module | Description |
---|---|
IcxTransactionBuilder | Builder class for IcxTransaction instance, which is for sending ICX. |
MessageTransactionBuilder | Builder class for MessageTransaction instance, which is for sending message data. Extends IcxTransactionBuilder class. |
DeployTransactionBuilder | Builder class for DeployTransaction instance, which is for deploying SCORE. Extends IcxTransactionBuilder class. |
CallTransactionBuilder | Builder class for CallTransaction instance, which is for invoking a state-transition function of SCORE. Extends IcxTransactionBuilder class. |
DepositTransactionBuilder | Builder class for DepositTransaction instance, which is for depositing to SCORE(or withdrawing from SCORE). Extends IcxTransactionBuilder class. |
CallBuilder | Builder class for Call instance, which is for invoking a read-only function of SCORE. |
Builder class for IcxTransaction
instance. IcxTransaction
is an object representing a transaction object used for sending ICX. The parameter details are as follows:
Parameter | Description |
---|---|
to |
An EOA address to receive coins, or SCORE address to execute the transaction. |
from |
An EOA address that created the transaction |
value (optional) |
Amount of ICX coins in loop to transfer. When ommitted, assumes 0. (1 icx = 10 ^ 18 loop) |
stepLimit |
Maximum step allowance that can be used by the transaction. |
nid |
Network ID ("0x1" for Mainnet, "0x2" for Testnet, etc) |
nonce |
An arbitrary number used to prevent transaction hash collision. |
version |
Protocol version ("0x3" for V3) |
timestamp |
Transaction creation time. timestamp is in microsecond. |
Creates an instance of IcxTransactionBuilder
class.
new IcxTransactionBuilder()
None
Setter method of 'to' property.
.to(to: string) => IcxTransactionBuilder
Parameter | Type | Description |
---|---|---|
to | string |
an EOA or SCORE address. |
IcxTransactionBuilder
- Returns an instance of itself
// Set `to` property.
const txObj = new IcxTransactionBuilder()
.to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
Setter method of 'from' property.
.from(from: string) => IcxTransactionBuilder
Parameter | Type | Description |
---|---|---|
from | string |
an EOA address. |
IcxTransactionBuilder
- Returns an instance of itself
// Set `from` property.
const txObj = new IcxTransactionBuilder()
.from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
Setter method of 'value' property.
.value(value: string|BigNumber|number) => IcxTransactionBuilder
Parameter | Type | Description |
---|---|---|
value | string , BigNumber , number |
the sending amount of ICX in loop unit. |
IcxTransactionBuilder
- Returns an instance of itself
// Set `value` property.
const txObj = new IcxTransactionBuilder()
.value(IconAmount.of(1, IconAmount.Unit.ICX).toLoop())
Setter method of 'stepLimit' property.
.stepLimit(stepLimit: string|BigNumber|number) => IcxTransactionBuilder
Parameter | Type | Description |
---|---|---|
stepLimit | string , BigNumber , number |
the amount of step limit. |
IcxTransactionBuilder
- Returns an instance of itself
// Set `value` property.
const txObj = new IcxTransactionBuilder()
.stepLimit(IconConverter.toBigNumber(100000))
Setter method of 'nid' property.
.nid(nid: string|BigNumber|number) => IcxTransactionBuilder
Parameter | Type | Description |
---|---|---|
nid | string , BigNumber , number |
a network ID. |
IcxTransactionBuilder
- Returns an instance of itself
// Set `nid` property.
const txObj = new IcxTransactionBuilder()
.nid(IconConverter.toBigNumber(1))
Setter method of 'nonce' property.
.nonce(nonce: string|BigNumber|number) => IcxTransactionBuilder
Parameter | Type | Description |
---|---|---|
nonce | string , BigNumber , number |
a nonce value. |
IcxTransactionBuilder
- Returns an instance of itself
// Set `nonce` property.
const txObj = new IcxTransactionBuilder()
.nonce(IconConverter.toBigNumber(1))
Setter method of 'version' property.
.version(version: string|BigNumber|number) => IcxTransactionBuilder
Parameter | Type | Description |
---|---|---|
version | string , BigNumber , number |
the version value. |
IcxTransactionBuilder
- Returns an instance of itself
// Set `version` property.
const txObj = new IcxTransactionBuilder()
.version(IconConverter.toBigNumber(3))
Setter method of 'timestamp' property.
.timestamp(version: string|BigNumber|number) => IcxTransactionBuilder
Parameter | Type | Description |
---|---|---|
timestamp | string , BigNumber , number |
timestamp value. (microsecond) |
IcxTransactionBuilder
- Returns an instance of itself
// Set `timestamp` property.
const txObj = new IcxTransactionBuilder()
.timestamp(1544596599371000)
Returns an IcxTransaction
instance which contains parameter you set.
.build() => IcxTransaction
None
IcxTransaction
- Returns an IcxTransaction
instance.
// Build `IcxTransaction` instance.
const txObj = new IcxTransactionBuilder()
.from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
.to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
.value(IconAmount.of(7, IconAmount.Unit.ICX).toLoop())
.stepLimit(IconConverter.toBigNumber(100000))
.nid(IconConverter.toBigNumber(3))
.nonce(IconConverter.toBigNumber(1))
.version(IconConverter.toBigNumber(3))
.timestamp(1544596599371000)
.build()
Builder class for MessageTransaction
instance. MessageTransaction
is an object representing a transaction object used for sending message data. It extends IcxTransaction
class, so instance parameters and methods of builder class are mostly identical to IcxTransaction
class, except for the following:
Parameter | Description |
---|---|
data |
A message data. Data type of the data should be lowercase hex string prefixed with '0x'. |
dataType |
Data type of data . Fixed string message is in value. |
For details of extended parameters and methods, see IcxTransactionBuilder section.
Creates an instance of MessageTransactionBuilder
class.
new MessageTransactionBuilder()
None
Setter method of 'data' property.
.data(data: string) => MessageTransactionBuilder
Parameter | Type | Description |
---|---|---|
data | string |
the data (hex string) to send. |
MessageTransactionBuilder
- Returns an instance of itself
// Set `data` property.
const txObj = new MessageTransactionBuilder()
.data(IconConverter.fromUtf8('Hello'))
Returns an MessageTransaction
instance which contains parameter you set.
.build() => MessageTransaction
None
MessageTransaction
- Returns an MessageTransaction
instance.
// Build `MessageTransaction` instance.
const txObj = new MessageTransactionBuilder()
.from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
.to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
.stepLimit(IconConverter.toBigNumber(100000))
.nid(IconConverter.toBigNumber(3))
.nonce(IconConverter.toBigNumber(1))
.version(IconConverter.toBigNumber(3))
.timestamp(1544596599371000)
.data(IconConverter.fromUtf8('Hello'))
.build()
Builder class for DeployTransaction
instance. DeployTransaction
is an object representing a transaction object used for deploying SCORE. It extends IcxTransaction
class, so instance parameters and methods of builder class are mostly identical to IcxTransaction
class, except for the following:
Parameter | Description |
---|---|
data |
A deploy object data. It contains 3 parameters: 1) contentType - Mime-type of the content. 2) content - Compressed SCORE data. 3) params (optional) - Function parameters delivered to on_install() or on_update() |
dataType |
Data type of data . Fixed string deploy is in value. |
For details of extended parameters and methods, see IcxTransactionBuilder section.
Creates an instance of DeployTransactionBuilder
class.
new DeployTransactionBuilder()
None
Setter method of 'contentType' property in 'data'.
.contentType(contentType: string) => DeployTransactionBuilder
Parameter | Type | Description |
---|---|---|
contentType | string |
the content type of content |
DeployTransactionBuilder
- Returns an instance of itself
// Set `contentType` property.
const txObj = new DeployTransactionBuilder()
.contentType('application/zip')
Setter method of 'content' property in 'data'.
.content(content: string) => DeployTransactionBuilder
Parameter | Type | Description |
---|---|---|
content | string |
the content to deploy. |
DeployTransactionBuilder
- Returns an instance of itself
// Set `content` property.
const txObj = new DeployTransactionBuilder()
.content('0x504b03040a0000000000d3a68e4d000000000000000...')
Setter method of 'params' property in 'data'.
.params(params: object) => DeployTransactionBuilder
Parameter | Type | Description |
---|---|---|
params | object |
Function parameters delivered to on_install() or on_update(). |
DeployTransactionBuilder
- Returns an instance of itself
// Set `params` property.
const txObj = new DeployTransactionBuilder()
.params({
initialSupply: IconConverter.toHex('100000000000'),
decimals: IconConverter.toHex(18),
name: 'StandardToken',
symbol: 'ST',
})
Returns an DeployTransaction
instance which contains parameter you set.
.build() => DeployTransaction
None
DeployTransaction
- Returns an DeployTransaction
instance.
// Build `DeployTransaction` instance.
const txObj = new DeployTransactionBuilder()
.from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
.to('cx0000000000000000000000000000000000000000')
.stepLimit(IconConverter.toBigNumber(2500000))
.nid(IconConverter.toBigNumber(3))
.nonce(IconConverter.toBigNumber(1))
.version(IconConverter.toBigNumber(3))
.timestamp(1544596599371000)
.contentType('application/zip')
.content('0x504b03040a0000000000d3a68e4d000000000000000...')
.params({
initialSupply: IconConverter.toHex('100000000000'),
decimals: IconConverter.toHex(18),
name: 'StandardToken',
symbol: 'ST',
})
.build()
Builder class for CallTransaction
instance. CallTransaction
is an object representing a transaction object used for invoking a state-transition function of SCORE. It extends IcxTransaction
class, so instance parameters and methods are mostly identical to IcxTransaction
class, except for the following:
Parameter | Description |
---|---|
data |
An object data for calling method. It contains 2 parameters: 1) method - The method name of SCORE API. 2) params (optional) - The input params for method |
dataType |
Data type of data . Fixed string call is in value. |
For details of extended parameters and methods, see IcxTransactionBuilder section.
Creates an instance of CallTransactionBuilder
class.
new CallTransactionBuilder()
None
Setter method of 'method' property in 'data'.
.method(method: string) => CallTransactionBuilder
Parameter | Type | Description |
---|---|---|
method | string |
the method name of SCORE API. |
CallTransactionBuilder
- Returns an instance of itself
// Set `method` property.
const txObj = new CallTransactionBuilder()
.method('transfer')
Setter method of 'params' property in 'data'.
.params(params: object) => CallTransactionBuilder
Parameter | Type | Description |
---|---|---|
params | object |
the input params for method. |
CallTransactionBuilder
- Returns an instance of itself
// Set `params` property.
const txObj = new CallTransactionBuilder()
.params({
_to: 'hxd008c05cbc0e689f04a5bb729a66b42377a9a497',
_value: IconConverter.toHex(IconAmount.of(1, IconAmount.Unit.ICX).toLoop()),
})
Returns an CallTransaction
instance which contains parameter you set.
.build() => CallTransaction
None
CallTransaction
- Returns an CallTransaction
instance.
// Build `CallTransaction` instance.
const txObj = new CallTransactionBuilder()
.from('hx902ecb51c109183ace539f247b4ea1347fbf23b5')
.to('cx3502b4dadbfcd654d26d53d8463f2929c2c3948d')
.stepLimit(IconConverter.toBigNumber('2000000'))
.nid(IconConverter.toBigNumber('3'))
.nonce(IconConverter.toBigNumber('1'))
.version(IconConverter.toBigNumber('3'))
.timestamp((new Date()).getTime() * 1000)
.method('transfer')
.params({
_to: 'hxd008c05cbc0e689f04a5bb729a66b42377a9a497',
_value: IconConverter.toHex(IconAmount.of(1, IconAmount.Unit.ICX).toLoop()),
})
.build()
Builder class for DepositTransaction
instance. DepositTransaction
is an object representing a transaction object used for depositing/withdrawing SCORE. It extends IcxTransaction
class, so instance parameters and methods are mostly identical to IcxTransaction
class, except for the following:
Parameter | Description |
---|---|
data |
An object data for depositing to SCORE. It contains 2 parameters: 1) action - Whether to deposit or withdraw. When making a withdrawal, id is required. 2) id (optional) - deposit id to withdraw. needed when withdraw deposit |
dataType |
Data type of data . Fixed string deposit is in value. |
For details of extended parameters and methods, see IcxTransactionBuilder section.
Creates an instance of DepositTransactionBuilder
class.
new DepositTransactionBuilder()
None
Setter method of 'action' property in 'data'.
.action(action: string) => DepositTransactionBuilder
Parameter | Type | Description |
---|---|---|
action | string |
Whether to deposit or withdraw. (add or withdraw ) |
DepositTransactionBuilder
- Returns an instance of itself
// Set `action` property.
const txObj = new DepositTransactionBuilder()
.action('add')
Setter method of 'id' property in 'data'.
.id(params: string) => DepositTransactionBuilder
Parameter | Type | Description |
---|---|---|
id | string |
Deposit id to withdraw |
DepositTransactionBuilder
- Returns an instance of itself
// Set `id` property.
const txObj = new DepositTransactionBuilder()
.id("0x8ed676ca8aeef92159f5bb1223db1e8bcf65ea8ea3d6ae9ed23e006407aa9fda")
Returns an DepositTransaction
instance which contains parameter you set.
.build() => DepositTransaction
None
DepositTransaction
- Returns an DepositTransaction
instance.
// Build `DepositTransaction` instance.
const txObj = new DepositTransactionBuilder()
.from('hx902ecb51c109183ace539f247b4ea1347fbf23b5')
.to('cx3502b4dadbfcd654d26d53d8463f2929c2c3948d')
.stepLimit(IconConverter.toBigNumber('2000000'))
.nid(IconConverter.toBigNumber('3'))
.nonce(IconConverter.toBigNumber('1'))
.version(IconConverter.toBigNumber('3'))
.timestamp((new Date()).getTime() * 1000)
.action('withdraw')
.id("0x8ed676ca8aeef92159f5bb1223db1e8bcf65ea8ea3d6ae9ed23e006407aa9fda")
.build()
Builder class for Call
instance. Call
is an object representing a transaction object used for invoking a read-only function of SCORE. The parameter details are as follows:
Parameter | Description |
---|---|
to |
a SCORE address to execute the call. |
data |
an object data for calling method. It contains 2 parameters: 1) method - The method name of SCORE API. 2) params (optional) - The input params for method |
dataType |
Data type of data . Fixed string call is in value. |
Creates an instance of CallBuilder
class.
new CallBuilder()
None
Setter method of 'to' property.
.to(to: string) => CallBuilder
Parameter | Type | Description |
---|---|---|
to | string |
a SCORE address. |
CallBuilder
- Returns an instance of itself
// Set `to` property.
const txObj = new CallBuilder()
.to('cxc248ee72f58f7ec0e9a382379d67399f45b596c7')
Setter method of 'method' property in 'data'.
.method(method: string) => CallBuilder
Parameter | Type | Description |
---|---|---|
method | string |
the method name of SCORE API. |
CallBuilder
- Returns an instance of itself
// Set `method` property.
const txObj = new CallBuilder()
.method('balanceOf')
Setter method of 'params' property in 'data'.
.params(params: object) => CallBuilder
Parameter | Type | Description |
---|---|---|
params | object |
the input params for method. |
CallBuilder
- Returns an instance of itself
// Set `params` property.
const txObj = new CallBuilder()
.params({
_owner: 'hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a'
})
Returns an Call
instance which contains parameter you set.
.build() => Call
None
Call
- Returns an Call
instance.
// Build `Call` instance.
const txObj = new CallBuilder()
.to('cxc248ee72f58f7ec0e9a382379d67399f45b596c7')
.method('balanceOf')
.params({ _owner: 'hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a' })
.build()
SignedTransaction
is a class for signing transaction object. It enables you to make signature, and signed transaction object by calling instance methods. Also, by passing SignedTransaction
instance to sendTransaction(), it will automatically generate transaction object including signature, and send to ICON node.
Creates an instance of SignedTransaction
class.
new SignedTransaction(transaction: IcxTransaction|MessageTransaction|CallTransaction|DeployTransaction, wallet: Wallet)
Parameter | Type | Description |
---|---|---|
transaction | IcxTransaction , MessageTransaction , CallTransaction , DeployTransaction |
a transaction object. |
wallet | Wallet |
wallet instance used for signing. |
Get a signature string.
.getSignature() => string
None
string
- a signature string.
/* Returns the signature */
const signature = new SignedTransaction(icxTransaction, wallet).getSignature()
// 'YV3eNgVjLFwXS65Bk...+lC90KgRBh7FtwE='
Get a raw signed transaction object.
.getProperties() => object
None
object
- the raw signed transaction object.
/* Returns the raw signed transaction object */
const signature = new SignedTransaction(icxTransaction, wallet).getProperties()
// {
// to: 'hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a',
// from: 'hx46293d558d3bd489c3715e7e3648de0e35086bfd',
// stepLimit: '0x186a0',
// nid: '0x3',
// version: '0x3',
// timestamp: '0x57ccd6ba074f8',
// value: '0x7',
// nonce: '0x1',
// signature: 'YV3eNgVjLFwXS65Bk...+lC90KgRBh7FtwE=',
// };
Get a raw transaction object of transaction
property.
.getRawTransaction() => object
None
object
- the raw transaction object of transaction
property.
/* Returns the signed transaction object */
const signature = new SignedTransaction(icxTransaction, wallet).getRawTransaction()
// {
// to: 'hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a',
// from: 'hx46293d558d3bd489c3715e7e3648de0e35086bfd',
// stepLimit: '0x186a0',
// nid: '0x3',
// version: '0x3',
// timestamp: '0x57ccd6ba074f8',
// value: '0x7',
// nonce: '0x1'
// };
HttpProvider
is a class representing HTTP-based provider. It is commonly used for setting provider url of IconService
instance. For details of network and node url, see ICON Networks document.
Creates an instance of HttpProvider
class.
new HttpProvider(url: string)
Parameter | Type | Description |
---|---|---|
url | string |
ICON node url |
IconAmount
is a class representing BigNumber value and unit data. It also provides unit conversion static functions. It enables you to manage different types of numeric data easily.
(IconAmount
contains static class property called Unit
, which has constant number
value of different types of unit digit. IconAmount.Unit.LOOP
is 0
, and IconAmount.Unit.ICX
is 18
.)
Creates an instance of IconAmount
class.
new IconAmount(value: string|BigNumber|number, digit: string|BigNumber|number)
Parameter | Type | Description |
---|---|---|
value | string , BigNumber , number |
the value of amount. |
digit | string , BigNumber , number |
the digit of unit. |
Note: According to official document of BigNumber.js, it is recommended to create BigNumbers from
string
values rather thannumber
values to avoid a potential loss of precision.
Creates an instance of IconAmount
class.
IconAmount.of(value: string|BigNumber|number, digit: string|BigNumber|number) => IconAmount
Parameter | Type | Description |
---|---|---|
value | string , BigNumber , number |
the value of amount. |
digit | string , BigNumber , number |
the digit of unit. |
Note: According to official document of BigNumber.js, it is recommended to create BigNumbers from
string
values rather thannumber
values to avoid a potential loss of precision.
IconAmount
- IconAmount instance.
// Returns IconAmount instance
const iconAmount = IconAmount.of('2', IconAmount.Unit.ICX);
Converts value property into string
.toString() => string
None
string
- The stringified value property of IconAmount instance.
// Returns stringified value property
const value = IconAmount.of('2', IconAmount.Unit.ICX).toString();
Get digit property.
.getDigit() => number
None
number
- The digit property of IconAmount instance.
// Returns digit property
const digit = IconAmount.of('2', IconAmount.Unit.ICX).getDigit();
Get value property converted into loop unit.
.toLoop() => BigNumber
None
BigNumber
- The value property converted into loop unit.
// Returns value property converted into loop unit.
const value = IconAmount.of('2', IconAmount.Unit.ICX).toLoop();
Converts value property into custom digit
.convertUnit(digit: string|BigNumber|number) => IconAmount
Parameter | Type | Description |
---|---|---|
digit | string , BigNumber , number |
the digit of unit. |
IconAmount
- The IconAmount instance converted into custom digit.
// Returns IconAmount instance converted into custom digit.
const value = IconAmount.of('2', IconAmount.Unit.ICX).convertUnit(IconAmount.Unit.LOOP);
IconConverter
is a utility module which contains conversion functions.
Converts UTF-8 text to hex string with '0x' prefix.
IconConverter.fromUtf8(value: string) => string
Parameter | Type | Description |
---|---|---|
value | string |
an UTF-8 text string. |
string
- a hex string with '0x' prefix
// Returns hex string
const value = IconConverter.fromUtf8('hello')
Converts string, hex string or BigNumber value to number.
IconConverter.toNumber(value: string|BigNumber) => number
Parameter | Type | Description |
---|---|---|
value | string , BigNumber |
a string, hex string or BigNumber type value |
number
- a value converted to number type.
// Returns number value
const value = IconConverter.toNumber('123')
Converts string, hex string or number value to BigNumber.
IconConverter.toBigNumber(value: string|number) => BigNumber
Parameter | Type | Description |
---|---|---|
value | string , number |
a string, hex string or number type value |
BigNumber
- a value converted to BigNumber type.
// Returns BigNumber value
const value = IconConverter.toBigNumber('123')
Converts string, number or BigNumber value to hex string.
IconConverter.toHex(value: string|number|BigNumber) => string
Parameter | Type | Description |
---|---|---|
value | string , number , BigNumber |
a string, number or BigNumber type value |
string
- a value converted to hex string with '0x' prefix.
// Returns hex string
const value = IconConverter.toHex('123')
Converts transaction object to raw transaction object.
IconConverter.toRawTransaction(transaction: IcxTransaction|MessageTransaction|CallTransaction|DeployTransaction) => object
Parameter | Type | Description |
---|---|---|
transaction | IcxTransaction , MessageTransaction , CallTransaction , DeployTransaction |
a transaction object |
object
- a raw transaction object.
const txObj = new IcxTransactionBuilder()
.from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
.to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
.value(IconAmount.of(7, IconAmount.Unit.ICX).toLoop())
.stepLimit(IconConverter.toBigNumber(100000))
.nid(IconConverter.toBigNumber(3))
.nonce(IconConverter.toBigNumber(1))
.version(IconConverter.toBigNumber(3))
.timestamp(1544596599371000)
.build()
// Returns raw transaction object
const rawTxObj = IconConverter.toRawTransaction(txObj)
IconHexadecimal
is a utility module which contains functions related to hex prefix.
Check whether string starts with '0x' prefix.
IconHexadecimal.is0xPrefix(str: string) => boolean
Parameter | Type | Description |
---|---|---|
str | string |
a string |
boolean
- returns true if string starts with '0x' prefix.
// Returns true if string starts with '0x' prefix
const value = IconHexadecimal.is0xPrefix('0x61')
Check whether string starts with 'hx' prefix.
IconHexadecimal.isHxPrefix(str: string) => boolean
Parameter | Type | Description |
---|---|---|
str | string |
a string |
boolean
- returns true if string starts with 'hx' prefix.
// Returns true if string starts with 'hx' prefix
const value = IconHexadecimal.isHxPrefix('hx902ecb51c109183ace539f247b4ea1347fbf23b5')
Check whether string starts with 'cx' prefix.
IconHexadecimal.isCxPrefix(str: string) => boolean
Parameter | Type | Description |
---|---|---|
str | string |
a string |
boolean
- returns true if string starts with 'cx' prefix.
// Returns true if string starts with 'cx' prefix
const value = IconHexadecimal.isCxPrefix('cxc248ee72f58f7ec0e9a382379d67399f45b596c7')
Add '0x' prefix to string.
IconHexadecimal.add0xPrefix(str: string) => string
Parameter | Type | Description |
---|---|---|
str | string |
a string |
string
- a string with '0x' prefix.
// Returns a string with '0x' prefix.
const value = IconHexadecimal.add0xPrefix('1234')
Add 'hx' prefix to string.
IconHexadecimal.addHxPrefix(str: string) => string
Parameter | Type | Description |
---|---|---|
str | string |
a string |
string
- a string with 'hx' prefix.
// Returns a string with 'hx' prefix.
const value = IconHexadecimal.addHxPrefix('902ecb51c109183ace539f247b4ea1347fbf23b5')
Add 'cx' prefix to string.
IconHexadecimal.addCxPrefix(str: string) => string
Parameter | Type | Description |
---|---|---|
str | string |
a string |
string
- a string with 'cx' prefix.
// Returns a string with 'cx' prefix.
const value = IconHexadecimal.addCxPrefix('c248ee72f58f7ec0e9a382379d67399f45b596c7')
Remove '0x' prefix from string.
IconHexadecimal.remove0xPrefix(str: string) => string
Parameter | Type | Description |
---|---|---|
str | string |
a string |
string
- a string without '0x' prefix.
// Returns a string without '0x' prefix.
const value = IconHexadecimal.remove0xPrefix('0x61')
Remove 'hx' prefix from string.
IconHexadecimal.removeHxPrefix(str: string) => string
Parameter | Type | Description |
---|---|---|
str | string |
a string |
string
- a string without 'hx' prefix.
// Returns a string without 'hx' prefix.
const value = IconHexadecimal.removeHxPrefix('hx902ecb51c109183ace539f247b4ea1347fbf23b5')
Remove 'cx' prefix from string.
IconHexadecimal.removeCxPrefix(str: string) => string
Parameter | Type | Description |
---|---|---|
str | string |
a string |
string
- a string without 'cx' prefix.
// Returns a string without 'cx' prefix.
const value = IconHexadecimal.removeCxPrefix('cxc248ee72f58f7ec0e9a382379d67399f45b596c7')
IconValidator
is a utility module which contains validation functions.
Check if input value is a private key type string.
IconValidator.isPrivateKey(privKey: any) => boolean
Parameter | Type | Description |
---|---|---|
privKey | any |
an input value |
boolean
- Returns true if the input value is a private key type string.
// Returns true if the input value is a private key type string.
const isPrivateKey = IconValidator.isPrivateKey('7abca1...20a9f1')
Check if input value is a EOA address type string.
IconValidator.isEoaAddress(address: any) => boolean
Parameter | Type | Description |
---|---|---|
address | any |
an input value |
boolean
- Returns true if the input value is a EOA address type string.
// Returns true if the input value is a EOA address type string.
const isEoaAddress = IconValidator.isEoaAddress('hxca12a...209f1')
Check if input value is a SCORE address type string.
IconValidator.isScoreAddress(address: any) => boolean
Parameter | Type | Description |
---|---|---|
address | any |
a input value |
boolean
- Returns true if the input value is a SCORE address type string.
// Returns true if the input value is a SCORE address type string.
const isScoreAddress = IconValidator.isScoreAddress('cx1b32a...99f01')
Check if input value is a EOA or SCORE address type string.
IconValidator.isAddress(address: any) => boolean
Parameter | Type | Description |
---|---|---|
address | any |
an input value |
boolean
- Returns true if the input value is a EOA or SCORE address type string.
// Returns true if the input value is a EOA or SCORE address type string.
const isAddress = IconValidator.isAddress('cx1b32a...99f01')
There are 6 types of error cases. Details are as below:
Error code | Description |
---|---|
DATA ERROR |
Exception class related to data type. |
FORMAT ERROR |
Exception class related to data format. |
WALLET ERROR |
Exception class related to wallet errors. |
RPC ERROR |
Exception class related to network errors. |
SCORE ERROR |
Exception class related to SCORE call error. |
NETWORK ERROR |
Exception class related to network errors. |