How to use the JSON-RPC API

Search…
When a user sends a transaction, they need to sign the data with their own private key. There are two major steps involved in signing the transaction, serializing the original transaction data and generating a signature with user's own private key. This document describes the process of generating a digital signature of transaction data.
Intended Audience
Someone who wants to develop the program which communicates with ICON network with languages whose SDK is unsupported
Purpose
Generating a valid transaction signature in ICON network.
Prerequisite
​Elliptic Curve Digital Signature Algorithm​
​Transaction​
​ICON JSON-RPC API v3​
How to Serialize Transaction Data
Before signing the data, the data needs to be serialized as bytes. This section describes how to serialize the transaction data. This document does not describe how to make the transaction data itself. Transaction message specification is defined in JSON-RPC API v3.
Precondition
Transaction data is in JSON format with some restrictions.
Allowed types in JSON
Type
Description
String
Normal string without U+0000 (NULL) character. ex) “Value”
Dictionary
Pairs of key and value. ex) {“key1”: “value1”, “key1”: “value2”}
Array
Series of values. ex) [“value1”, “value2”]
Null
null
Serialize
ICON follows the JSON-RPC v2.0 protocol spec. A signed transaction request looks like the following:
{
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
        "version": "0x3",
        "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
        "to": "hx5bfdb090f43a808005ffc27c25b213145e80b7cd",
        "value": "0xde0b6b3a7640000",
        "stepLimit": "0x12345",
        "timestamp": "0x563a6cf330136",
        "nid": "0x1",
        "nonce": "0x1",
        "signature": "X1tpJdHBvqroonpTbdsNEur7KAeYcZd9XGa39AkW51Uck8EqgJnioedm5W2jZSQuBzZJHWm0Uf5BeXSmXoOByAA="
    }
}
Transaction data is serialized by concatenating key, value pairs in params with . as a delimiter. Our final goal is generating the signature of transaction data, therefore, the signature field shown above example is not part of the data to be serialized. Adding the method name, “icx_sendTransaction”, to the serialized string as a prefix completes the serialization process.
icx_sendTransaction.<key1>.<value1>....<keyN>.<valueN>
Make sure that all the special characters in string must be UTF-8 encoded.
String type
Apply UTF-8 encoding to the text. Characters listed below should be escaped with \. String must not have any null character, U+0000.
Name
Backslash (REVERSE SOLIDUS)
Period (FULL STOP)
Left curly bracket
Right curly bracket
Left square bracket
Right square bracket
Shape
\
.
{
}
[
]
UTF-8
0x5C
0x2E
0x7B
0x7D
0x5B
0x5D
Dictionary type
Enclosed with { and }, and key/value pairs are separated with .. Every keys in dictionary are string type, therefore, the same encoding rules apply. The order of keys in the serialized data follows the natural ordering of the UTF-8 encoded byte comparison (it’s same as Unicode string order).
{<key1>.<value1>.<key2>.<value2>....<keyN>.<valueN>}
Example:
{
    "method": "transfer",
    "params": {
        "to": "hxab2d8215eab14bc6bdd8bfb2c8151257032ecd8b",
        "value": "0x1"
    }
}
Serialized as
{method.transfer.params.{to.hxab2d8215eab14bc6bdd8bfb2c8151257032ecd8b.value.0x1}}
Array type
Enclosed with [ and ]. All values are separated with ..
[<value1>.<value2>.<value3>....<valueN>]
Null type
Null will be represented as an escaped zero.
\0
Example
ICX transfer
Original JSON request:
{
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
        "version": "0x3",
        "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
        "to": "hx5bfdb090f43a808005ffc27c25b213145e80b7cd",
        "value": "0xde0b6b3a7640000",
        "stepLimit": "0x12345",
        "timestamp": "0x563a6cf330136",
        "nid": "0x1",
        "nonce": "0x1"
    }
}
Serialized params:
icx_sendTransaction.from.hxbe258ceb872e08851f1f59694dac2558708ece11.nid.0x1.nonce.0x1.stepLimit.0x12345.timestamp.0x563a6cf330136.to.hx5bfdb090f43a808005ffc27c25b213145e80b7cd.value.0xde0b6b3a7640000.version.0x3
SCORE API invocation
Original JSON request:
{
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
        "version": "0x3",
        "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
        "to": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
        "stepLimit": "0x12345",
        "timestamp": "0x563a6cf330136",
        "nid": "0x1",
        "nonce": "0x1",
        "dataType": "call",
        "data": {
            "method": "transfer",
            "params": {
                "to": "hxab2d8215eab14bc6bdd8bfb2c8151257032ecd8b",
                "value": "0x1"
            }
        }
    }
}
Serialized params:
icx_sendTransaction.data.{method.transfer.params.{to.hxab2d8215eab14bc6bdd8bfb2c8151257032ecd8b.value.0x1}}.dataType.call.from.hxbe258ceb872e08851f1f59694dac2558708ece11.nid.0x1.nonce.0x1.stepLimit.0x12345.timestamp.0x563a6cf330136.to.cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32.version.0x3
How to Create Transaction Signature
This section describes how to create a valid signature for a transaction using the private key associated with a specific wallet address.
Required data
Private key
The private key of the from address from which the transaction request was made.
Transaction hash
32 bytes (256-bit) hash data which is created by hashing the serialized transaction data using SHA3_256.
Create signature
The first step is making a serialized signature. Using the secp256k1 library, create a recoverable ECDSA signature of a transaction hash. This ensures that the transaction was originated from the private key owner, and the transaction message received by the recipient is not compromised. The resulting output should be 64 bytes serialized signature (R, S) with 1 byte recovery id (V).
The final step is to encode the generated signature as a Base64-encoded string.
Steps of How-to
How to Generate Transaction Signature in Python
Below is the example of creating a signature in python.
Here is a sample transaction request message. We will create a signature for the transaction data.
{
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
        "version": "0x3",
        "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
        "to": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
        "value": "0xde0b6b3a7640000",
        "stepLimit": "0x12345",
        "timestamp": "0x563a6cf330136",
        "nid": "0x1"
    }
}
step1: Serialize transaction data.
icx_sendTransaction.from.hxbe258ceb872e08851f1f59694dac2558708ece11.nid.0x1.stepLimit.0x12345.timestamp.0x563a6cf330136.to.cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32.value.0xde0b6b3a7640000.version.0x3
step2: Create a transaction signature.
step2-1: Hash the serialized transaction data.
step2-2: Create a recoverable ECDSA signature.
step2-3: Encode the generated recoverable ECDSA signature as a Base64-encoded string.
import base64
import hashlib
import secp256k1
​
serialized_transaction = "icx_sendTransaction.from.hxbe258ceb872e08851f1f59694dac2558708ece11.nid.0x1.stepLimit.0x12345.timestamp.0x563a6cf330136.to.cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32.value.0xde0b6b3a7640000.version.0x3"
​
# transaction_hash
# result: b'z\xdc\xa3\[email protected]\x19{\xc0\xc5\xe3b\xc3I\x84&k\xeb\xbc\xd2\xda\xe2\xfd\x06\x08\x95TR[\x9b\xfc\xd0\xff'
msg_hash = hashlib.sha3_256(serialized_transaction.encode()).digest()
​
# prepare the private key (this private key is for example purpose)
private_key = b'\x870\x91*\xef\xedB\xac\x05\x8f\xd3\xf6\xfdvu8\x11\x04\xd49\xb3\xe1\x1f\x17\x1fTR\xd4\xf9\x19mL'
​
# create a private key object
private_key_object = secp256k1.PrivateKey(private_key)
​
# create a recoverable ECDSA signature
recoverable_signature = private_key_object.ecdsa_sign_recoverable(msg_hash, raw=True)
​
# convert the result from ecdsa_sign_recoverable to a tuple composed of 64 bytes and an integer denominated as recovery id.
signature, recovery_id = private_key_object.ecdsa_recoverable_serialize(recoverable_signature)
recoverable_sig = bytes(bytearray(signature) + recovery_id.to_bytes(1, 'big'))
​
# base64 encode
transaction_signature = base64.b64encode(recoverable_sig)
​
# transaction_signature: b'HNsFOK1qRkVKMB8ePZhKg/ELmT53MmnZn4ftt2sD69VdobB94BT0h52Bb8ven53186A9u+eIiIiWrSu8VjMUpwE='
Summary
So far, we have learned about the rule of serializing transaction data, a process of converting from serialized transaction data to transaction signature and the list of libraries used to generate a signature. Be aware that you can not generate a valid transaction signature if you omit process or break any rule.
How to estimate required STEP
Next - Getting Started
How to Use the Nexus Portal
Last modified 5mo ago
Copy link
On this page
Intended Audience
Purpose
Prerequisite
How to Serialize Transaction Data
How to Create Transaction Signature
Steps of How-to
Summary