Search…
ICON Governance SCORE APIs
This page needs to be updated for ICON 2.0 new system SCORE architecture.
This document describes APIs that Governance SCORE provides.

Overview

    Governance SCORE is a built-in SCORE that manages adjustable characteristics of ICON network.
    Address: cx0000000000000000000000000000000000000001

Value Types

By default, Values in all JSON-RPC messages are in string form. The most commonly used Value types are as follows.
Value Type
Description
Example
T_ADDR_EOA
"hx" + 40 digits HEX string
hxbe258ceb872e08851f1f59694dac2558708ece11
T_ADDR_SCORE
"cx" + 40 digits HEX string
cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32
T_HASH
"0x" + 64 digits HEX string
0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238
T_INT
"0x" + lowercase HEX string
0xa
T_STR
string
hello
T_IMPORT_STMT
Import statement string
"{'json': [], 'os': ['path'], 'base.exception': ['ExceptionCode']}"
T_BIN_DATA
"0x" + lowercase HEX string (the length of string should be even)
0x34b2
T_SIG
base64 encoded string
VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=

Import statement

Grammar

import_stmt: "{" import_element ("," import_element) "}" import_element: (import_name | import_from) import_name: dotted_name ": []" Import_from: dotted_name ": [" dotted_names "]" dotted_names: dotted_name ("," dotted_name) dotted_name: "'"NAME ("." NAME)*"'" NAME: Not an empty string

Examples

python import
import statement
import json
{ 'json' : [] }
from json import *
{ 'json' : [] }
from os import path
{ 'os' : ['path'] }
from base.exception import ExceptionCode
{ 'base.exception' : ['ExceptionCode'] }
import json from os import path from base.exception import ExceptionCode
{ 'json' : [], 'os' : ['path'], 'base.exception' : ['ExceptionCode'] }

Methods List

Query Methods

Query method does not change state. Read-only.

getScoreStatus

    Queries the current status of the given SCORE.
    current indicates the currently active SCORE instance, while next is the SCORE code that has been requested to install or update, but not activated yet.
    [Fee 2.0] Checks the deposit information of the given SCORE.

Parameters

Key
Value Type
Description
address
T_ADDR_SCORE
SCORE address whose status be checked

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"to": "cx0000000000000000000000000000000000000001",
7
"dataType": "call",
8
"data": {
9
"method": "getScoreStatus",
10
"params": {
11
"address": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32"
12
}
13
}
14
}
15
}
Copied!
Response: SCORE install case
1
// Response - install requested: under auditing
2
{
3
"jsonrpc": "2.0",
4
"id": 100,
5
"result": {
6
"next": {
7
"status": "pending",
8
"deployTxHash": "0xe0f6dc6607aa9b5550cd1e6d57549f67fe9718654cde15258922d0f88ff58b27"
9
}
10
}
11
}
Copied!
1
// Response - audit completed: accepted
2
{
3
"jsonrpc": "2.0",
4
"id": 100,
5
"result": {
6
"current": {
7
"status": "active",
8
"deployTxHash": "0xe0f6dc6607aa9b5550cd1e6d57549f67fe9718654cde15258922d0f88ff58b27",
9
"auditTxHash": "0x644dd57fbb65b49a49bcaf5e7685e01d53dc321f1cfb7dbbf8f4306265745292"
10
}
11
}
12
}
Copied!
1
// Response - audit completed: rejected
2
{
3
"jsonrpc": "2.0",
4
"id": 100,
5
"result": {
6
"next": {
7
"status": "rejected",
8
"deployTxHash": "0xe0f6dc6607aa9b5550cd1e6d57549f67fe9718654cde15258922d0f88ff58b27",
9
"auditTxHash": "0x644dd57fbb65b49a49bcaf5e7685e01d53dc321f1cfb7dbbf8f4306265745292"
10
}
11
}
12
}
Copied!
Response: SCORE update case
1
// Response - update requested: under auditing
2
{
3
"jsonrpc": "2.0",
4
"id": 100,
5
"result": {
6
"current": {
7
"status": "active",
8
"deployTxHash": "0xe0f6dc6607aa9b5550cd1e6d57549f67fe9718654cde15258922d0f88ff58b207",
9
"auditTxHash": "0x644dd57fbb65b49a49bcaf5e7685e01d53dc321f1cfb7dbbf8f4306265745292"
10
},
11
"next": {
12
"status": "pending",
13
"deployTxHash": "0xe0f6dc6607aa9b5550cd1e6d57549f67fe9718654cde15258922d0f88ff58b207"
14
}
15
}
16
}
Copied!
1
// Response - update requested, audit completed: rejected
2
{
3
"jsonrpc": "2.0",
4
"id": 100,
5
"result": {
6
"current": {
7
"status": "active",
8
"deployTxHash": "0xe0f6dc6607aa9b5550cd1e6d57549f67fe9718654cde15258922d0f88ff58b27",
9
"auditTxHash": "0x644dd57fbb65b49a49bcaf5e7685e01d53dc321f1cfb7dbbf8f4306265745292"
10
},
11
"next": {
12
"status": "rejected",
13
"deployTxHash": "0xe0f6dc6607aa9b5550cd1e6d57549f67fe9718654cde15258922d0f88ff58b27",
14
"auditTxHash": "0x644dd57fbb65b49a49bcaf5e7685e01d53dc321f1cfb7dbbf8f4306265745292"
15
}
16
}
17
}
Copied!
Response: (Fee 2.0) SCORE deposit status
depositInfo field will be shown when there is a deposit in the SCORE.
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": {
5
"current": {
6
"status": "active",
7
"deployTxHash": "0x19793f41b8e64fc31190c6a70a103103da1f4bc81bc829fa72c852a5e388fe8c"
8
},
9
"depositInfo": {
10
"scoreAddress": "cx216e1468b780ac1b54c328d19ea23a35a6899e55",
11
"deposits": [
12
{
13
"id": "0x64b118d4a3c2b3b93362a0f3ea06e5519de42449523465265b85509041e69011",
14
"sender": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb",
15
"depositAmount": "0x10f0cf064dd59200000",
16
"depositUsed": "0x0",
17
"created": "0x16",
18
"expires": "0x13c696",
19
"virtualStepIssued": "0x9502f9000",
20
"virtualStepUsed": "0x329a6"
21
}
22
],
23
"availableVirtualStep": "0x9502c665a",
24
"availableDeposit": "0xf3f20b8dfa69d00000"
25
}
26
}
27
}
Copied!
Response: error case
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"error": {
5
"code": -32032,
6
"message": "SCORE not found"
7
}
8
}
Copied!

getStepPrice

    Returns the current step price in loop.

Parameters

None

Returns

T_INT - integer of the current step price in loop (1 ICX == 10^18 loop).

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"to": "cx0000000000000000000000000000000000000001",
7
"dataType": "call",
8
"data": {
9
"method": "getStepPrice"
10
}
11
}
12
}
Copied!
Response
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": "0x2540be400"
5
}
Copied!

getStepCosts

    Returns a table of the step costs for each actions.

Parameters

None

Returns

T_DICT - a dict: key - camel-cased action strings, value - step costs in integer

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"to": "cx0000000000000000000000000000000000000001",
7
"dataType": "call",
8
"data": {
9
"method": "getStepCosts"
10
}
11
}
12
}
Copied!
Response
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": {
5
"default": "0x186a0",
6
"contractCall": "0x61a8",
7
"contractCreate": "0x3b9aca00",
8
"contractUpdate": "0x5f5e1000",
9
"contractDestruct": "-0x11170",
10
"contractSet": "0x7530",
11
"get": "0x0",
12
"set": "0x140",
13
"replace": "0x50",
14
"delete": "-0xf0",
15
"input": "0xc8",
16
"eventLog": "0x64",
17
"apiCall": "0x2710"
18
}
19
}
Copied!

getMaxStepLimit

    Returns the maximum step limit value that any SCORE execution should be bounded by.

Parameters

Key
Value Type
Description
contextType
string
'invoke' for sendTransaction, 'query' for call

Returns

T_INT - integer of the maximum step limit

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"to": "cx0000000000000000000000000000000000000001",
7
"dataType": "call",
8
"data": {
9
"method": "getMaxStepLimit",
10
"params": {
11
"contextType": "invoke"
12
}
13
}
14
}
15
}
Copied!
Response
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": "0x9502f900"
5
}
Copied!

isInScoreBlackList

    Returns "0x1" if the given address is in the deployer list.

Parameters

Key
Value Type
Description
address
T_ADDR_SCORE
SCORE address to query

Returns

T_INT - "0x1" if the SCORE address is in the black list, otherwise "0x0"

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"to": "cx0000000000000000000000000000000000000001",
7
"dataType": "call",
8
"data": {
9
"method": "isInScoreBlackList",
10
"params": {
11
"address": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32"
12
}
13
}
14
}
15
}
Copied!
Response
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": "0x1"
5
}
Copied!

getVersion

    Returns the version of Governance SCORE

Returns

T_STR - version string

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"to": "cx0000000000000000000000000000000000000001",
7
"dataType": "call",
8
"data": {
9
"method": "getVersion"
10
}
11
}
12
}
Copied!
Response
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": "0.0.7"
5
}
Copied!

isInImportWhiteList

    Returns True if import statement is in the import white list.

Parameters

Key
Value Type
Description
importStmt
T_IMPORT_STMT
Import statement

Returns

T_INT - "0x1" if the import statement is in the import white list, otherwise "0x0"

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"to": "cx0000000000000000000000000000000000000001",
7
"dataType": "call",
8
"data": {
9
"method": "isInImportWhiteList",
10
"params": {
11
"importStmt": "{'json': [], 'os': ['path'], 'base.exception': ['ExceptionCode']}"
12
}
13
}
14
}
15
}
Copied!
Response
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": "0x0"
5
}
Copied!

getServiceConfig

    Returns table about server config.

Parameters

None

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"to": "cx0000000000000000000000000000000000000001",
7
"dataType": "call",
8
"data": {
9
"method": "getServiceConfig"
10
}
11
}
12
}
Copied!
Response
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": {
5
"FEE": "0x1",
6
"AUDIT": "0x1",
7
"DEPLOYER_WHITE_LIST": "0x0",
8
"SCORE_PACKAGE_VALIDATOR": "0x1"
9
}
10
}
Copied!

getRevision

    Returns info about revision.

Parameters

None

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"to": "cx0000000000000000000000000000000000000001",
7
"dataType": "call",
8
"data": {
9
"method": "getRevision"
10
}
11
}
12
}
Copied!
Response
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": {
5
"code": "0x4",
6
"name": "1.3.0"
7
}
8
}
Copied!

getProposal

    Query information about the network proposal.

Parameters

Key
Value Type
Description
id
T_HASH
Transaction hash of the registered network proposal

Returns

T_DICT - Information of the network proposal in dict

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"version": "0x3",
7
"from": "hx8f21e5c54f006b6a5d5fe65486908592151a7c57",
8
"to": "cx0000000000000000000000000000000000000001",
9
"timestamp": "0x563a6cf330136",
10
"dataType": "call",
11
"data": {
12
"method": "getProposal",
13
"params": {
14
"id": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
15
}
16
}
17
}
18
}
Copied!
Response
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"result": {
5
"id" : "0xb903239f8543d0..",
6
"proposer" : "hxbe258ceb872e08851f1f59694dac2558708ece11",
7
"proposerName" : "P-Rep A",
8
"status" : "0x0",
9
"startBlockHeight" : "0x1",
10
"endBlockHeight" : "0x65",
11
"vote": {
12
"agree": {
13
"list":[{
14
"id": "0xb903239f854..",
15
"timestamp": "0x563a6cf330136",
16
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb",
17
"name": "P-Rep B",
18
"amount": "0x1"
19
}, .. ],
20
"amount": "0x12345"
21
},
22
"disagree": {
23
"list": [{
24
"id": "0xa803239f854..",
25
"timestamp": "0x563a6cf330136",
26
"address": "hxbe258ceb872e08851f1f59694dac2558708ece11",
27
"name": "P-Rep C",
28
"amount": "0x1"
29
}, .. ],
30
"amount": "0x123"
31
},
32
"noVote": {
33
"list": ["hx31258ceb872e08851f1f59694dac2558708ece11", .. , "hx31258ceb872e08851f1f59694dac2558708eceff"],
34
"amount": "0x12312341234a"
35
},
36
},
37
"contents": {
38
"title": "Disqualify P-Rep C",
39
"description": "P-Rep C does not maintain node",
40
"type": "0x3",
41
"value": {
42
"address": "hxbe258ceb872e08851f1f59694dac2558708ece11"
43
}
44
}
45
}
46
}
Copied!

getProposals

    Query all of the network proposals.

Parameters

Key
Value Type
Description
type
T_INT
Type for querying (optional)
status
T_INT
Status for querying (optional)

Returns

T_LIST - List of summarized information of network proposals in dict.

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_call",
5
"params": {
6
"version": "0x3",
7
"from": "hx8f21e5c54f006b6a5d5fe65486908592151a7c57",
8
"to": "cx0000000000000000000000000000000000000001",
9
"timestamp": "0x563a6cf330136",
10
"dataType": "call",
11
"data": {
12
"method": "getProposals",
13
"params": {
14
"type": "0x3",
15
"status": "0x0"
16
}
17
}
18
}
19
}
Copied!
Response
1
{
2
"jsonrpc":"2.0",
3
"id":1234,
4
"result":{
5
"proposals":[
6
{
7
"id":"0xb903239f8543..",
8
"proposer":"hxbe258ceb872e08851f1f59694dac2558708ece11",
9
"proposerName":"P-Rep A",
10
"status":"0x0",
11
"startBlockHeight":"0x1",
12
"endBlockHeight":"0x65",
13
"vote":{
14
"agree":{
15
"count":"0x1",
16
"amount":"0x12312341234a"
17
},
18
"disagree":{
19
"count":"0x1",
20
"amount":"0x12312341234a"
21
},
22
"noVote":{
23
"count":"0x1",
24
"amount":"0x12312341234a"
25
}
26
},
27
"contents":{
28
"title":"Disqualify P-Rep C",
29
"description":"P-Rep C does not maintain node",
30
"type":"0x3",
31
"value":{
32
"address":"hxbe258ceb872e08851f1f59694dac2558708ece11"
33
}
34
}
35
}, .. ]
36
}
37
}
Copied!

Invoke Methods

Invoke method can initiate state transition.

acceptScore

    Accepts SCORE deployment request.
    This method can be invoked only from the addresses that are in the auditor list.
    The accepted SCORE will be executing from the next block.

Parameters

Key
Value Type
Description
txHash
T_HASH
Transaction hash of the SCORE deploy transaction.

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 1234,
4
"method": "icx_sendTransaction",
5
"params": {
6
"version": "0x3",
7
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
8
"to": "cx0000000000000000000000000000000000000001",
9
"stepLimit": "0x12345",
10
"timestamp": "0x563a6cf330136",
11
"nonce": "0x1",
12
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
13
"dataType": "call",
14
"data": {
15
"method": "acceptScore",
16
"params": {
17
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
18
}
19
}
20
}
21
}
Copied!

rejectScore

    Rejects SCORE deployment request.
    This can be invoked only from the addresses that are in the auditor list.

Parameters

Key
Value Type
Description
txHash
T_HASH
Transaction hash of the SCORE deploy request.
reason
T_TEXT
Reason for rejecting

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 1234,
4
"method": "icx_sendTransaction",
5
"params": {
6
"version": "0x3",
7
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
8
"to": "cx0000000000000000000000000000000000000001",
9
"stepLimit": "0x12345",
10
"timestamp": "0x563a6cf330136",
11
"nonce": "0x1",
12
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
13
"dataType": "call",
14
"data": {
15
"method": "rejectScore",
16
"params": {
17
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
18
"reason": "SCORE cannot use network api"
19
}
20
}
21
}
22
}
Copied!

addAuditor

    Adds a new address to the auditor list.
    Only the addresses registered in the auditor list can call acceptScore and rejectScore.
    Only the owner of the Governance SCORE can call this function.

Parameters

Key
Value Type
Description
address
T_ADDR_EOA
New EOA address that will be added to the auditor list

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_sendTransaction",
5
"params": {
6
"version": "0x3",
7
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
8
"to": "cx0000000000000000000000000000000000000001",
9
"stepLimit": "0x30000",
10
"timestamp": "0x563a6cf330136",
11
"nonce": "0x1",
12
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
13
"dataType": "call",
14
"data": {
15
"method": "addAuditor",
16
"params": {
17
"address": "hx2d54d5ca2a1dffbcfc3fb2c86cc07cb826f6b931"
18
}
19
}
20
}
21
}
Copied!

removeAuditor

    Removes the address from the auditor list.
    The address removed from the auditor list cannot call acceptScore and rejectScore afterward.
    This function can be invoked only by either Governance SCORE owner or the auditor herself.

Parameters

Key
Value Type
Description
address
T_ADDR_EOA
EOA address in the auditor list

Examples

Request
1
{
2
"jsonrpc": "2.0",
3
"id": 100,
4
"method": "icx_sendTransaction",
5
"params": {
6
"version": "0x3",
7
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
8
"to": "cx0000000000000000000000000000000000000001",
9
"stepLimit": "0x30000",
10
"timestamp": "0x563a6cf330136",
11
"nonce": "0x1",
12
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
13
"dataType": "call",
14
"data": {
15
"method": "removeAuditor",
16
"params": {
17
"address": "hx2d54d5ca2a1dffbcfc3fb2c86cc07cb826f6b931"
18
}
19
}
20
}
21
}
Copied!

registerProposal

    Register the network proposal
    This function can be invoked only by the main P-Reps.

Parameters

Key
Value Type
Description
title
T_STR
Title of the network proposal
description
T_STR
Description of the network proposal
type
T_INT
Type of the network proposal