POS RPC

ConFi-Conflux · 3 December 2021 06:10

id	title	custom_edit_url	keywords
pos_rpc	PoS JSON RPC	https://github.com/Conflux-Chain/conflux-doc/edit/master/docs/pos-rpc.md	conflux pos-rpc sdk

conflux-rust introduces the PoS finality starting from v1.2.0 to speed up the finality of blocks and prevent 51% attacks. PoS finality will introduce an independent PoS chain for PoS consensus and finalizing PoW blocks. Correspondingly, PoS also has its own RPC methods for obtaining data from the PoS chain.

Currently, only the archive nodes of conflux-rust can provide PoS RPC service to the public. public_rpc_apis needs to be configured to open RPC.

You can add the pos group to the current RPC method group.

public_rpc_apis = "safe,pos"

Or just set public_rpc_apis to all to open all RPC methods.

public_rpc_apis = "all"

Basic Concepts

epoch

The concept of epoch is also used in PoS. However, different from the epoch in PoW, an epoch in PoS represents the term of a committee, starting from term 1. Each epoch is equivalent to one hour on average. After each epoch, a part of the members of the committee are replaced. The rewards for participating in PoS consensus are also given on an epoch basis.

round

A PoS chain will on average perform one round of consensus every minute (i.e. try to generate a PoS block). This means that each epoch will have 60 rounds, and with each new epoch, the round will start from 1 again.

Note: Not every round will generate a block. there may be network or consensus failures preventing a block from generating.

block.number

The block.number is the height of the block, and is added by one for each new block generated.

After a PoS block is proposed by a committee member, it will be sent to the network for voting. When the block collects enough votes, it is labeled as voted. However, the block has yet been committed. When three consecutive blocks are created, the block corresponding to the first round will be submitted. Then its state will change from voted to committed.

pivotDecision

pivotDecision is the PoS chain’s final decision on a block in the PoW chain. Once a block in the PoW is referenced by the PoS, the PoW block is finalized and there will be no further reversion. Blocks in the PoS chain will include PivotDecision attributes, indicating that this PoS block has finalized a block in the PoW chain. The pivotDecision is the block number or hash value of a block in the PoW chain.

PoS Address

Unlike the format of the PoW address, the PoS account address is a 256-bit hash value, e.g.

0x046ca462890f25ed9394ca9f92c979ff48e1738a81822ecab96d83813c1a433c

PoS Model

AccountStatus

After an account registers to participate in PoS consensus, or adds staking to votes, the votes will first go into the inQueue state and then become locked after seven days.
When the user makes an unlock command, the votes to be unlocked will first go into the outQueue state. Then it also takes seven days to become unlocked.

availableVotes: QUANTITY - the number of votes currently available for the account. Equals to sum inQueue + locked
forfeited: QUANTITY - the number of votes that are locked and cannot be retrieved if the account is identified as malicious.
forceRetired: [QUANTITY] - the number of votes that are forced to retire
inQueue: Array of VotesInQueue - the number of votes that are currently waiting to be locked
locked: QUANTITY - the number of votes that are currently locked
outQueue: Array of VotesInQueue - the number of votes that are currently waiting to be unlocked
unlocked: QUANTITY - the number of votes that are currently unlocked

Decision

The PoS chain’s decision on the height of the PoW chain. The block of the PoW that is decided by the PoS chain is the Finalized block.

height: QUANTITY - the height of the PoW block
blockHash: HASH - the hash value of the PoW block

VotesInQueue

The information regarding a user’s in-queue votes.

endBlockNumber: QUANTITY - block number when the state ends
power: QUANTITY - number of votes in the current status

RPCs

pos_getStatus

Returns the current status of the PoS chain.

Parameters

Empty

Returns

Object - PoS status object.

epoch: QUANTITY - The current epoch number of the PoS chain.
latestCommitted: QUANTITY - The number of the latest committed block. Committed blocks will not be reverted
latestVoted: [QUANTITY] - The number of the latest successfully voted block, or null (if there are no blocks completed voting).
pivotDecision: Decision - The PoS chain’s finalized decision about the latest PoW pivot block.

Example

Request

curl --location --request POST 'http://localhost:12537' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "pos_getStatus",
    "params": []
}'

Result

{
    "jsonrpc": "2.0",
    "result": {
        "epoch": "0x56",
        "latestCommitted": "0x140c",
        "latestVoted": "0x140e",
        "pivotDecision": {
          "height": "0x113af0",
          "blockHash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"
        }
    },
    "id": 1
}

pos_getAccount

Get the PoS account information

Parameters

ADDRESS: 32 Bytes - PoS account address
[QUANTITY]: block number, optional for querying the status of the account at a certain block height

params: [
  "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b",
  "0x100"
]

Returns

Object - the account object, or null (if the account corresponding to the address does not exist)

address: ADDRESS - the account address
blockNumber: QUANTITY - the block number corresponding to the status
status: OBJECT - the user’s current status, see Account Status for more information

Example

Request

curl --location --request POST 'http://localhost:12537' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "pos_getAccount",
    "params": ["0x046ca462890f25ed9394ca9f92c979ff48e1738a81822ecab96d83813c1a433c"]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "address": "0x046ca462890f25ed9394ca9f92c979ff48e1738a81822ecab96d83813c1a433c",
        "blockNumber": "0x14a7",
        "status": {
            "availableVotes": "0x513",
            "forfeited": "0x0",
            "forceRetired": null,
            "inQueue": [],
            "locked": "0x513",
            "outQueue": [],
            "unlocked": "0x0"
        }
    },
    "id": 1
}

pos_getCommittee

Get the current PoS committee information in default. It is also able to get the committee information for a block in history by specifying the blockNumber.

Parameters

[QUANTITY]: block number, optional for querying the committee information at a certain block height

Returns

currentCommittee: OBJECT - current committee members, see CurrentCommittee for more information
elections: Array - nodes who are running for election

CurrentCommittee

Current committee information

epochNumber: QUANTITY - epoch number of the committee term
nodes: Array of CommitteNode - list of committee members
quorumVotingPower: QUANTITY - the minimum number of votes needed to reach consensus
totalVotingPower: QUANTITY - the total number of votes of the current committee members

CommitteNode

Committee member information

address: ADDRESS - account address
votingPower: QUANTITY - number of votes

Election

isFinalized: BOOLEAN - whether the election is finalized or not
startBlockNumber: QUANTITY - the starting block number
topElectingNodes: Array of CommitteNode - the top ranked 50 nodes after election

Example

Request

curl --location --request POST 'http://localhost:12537' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "pos_getCommittee",
    "params": []
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "currentCommittee": {
            "epochNumber": "0x5a",
            "nodes": [
                {
                    "address": "0x046ca462890f25ed9394ca9f92c979ff48e1738a81822ecab96d83813c1a433c",
                    "votingPower": "0xc8"
                },
                {
                    "address": "0x459b19e745eb410c3696ff1ed15f9de9bb46aa5fefc27b0b6e8b8d7aaadfe8c0",
                    "votingPower": "0x32"
                }
            ],
            "quorumVotingPower": "0xa7",
            "totalVotingPower": "0xfa"
        },
        "elections": [
            {
                "isFinalized": false,
                "startBlockNumber": "0x1518",
                "topElectingNodes": [
                    {
                        "address": "0x046ca462890f25ed9394ca9f92c979ff48e1738a81822ecab96d83813c1a433c",
                        "votingPower": "0x2a"
                    },
                    {
                        "address": "0x459b19e745eb410c3696ff1ed15f9de9bb46aa5fefc27b0b6e8b8d7aaadfe8c0",
                        "votingPower": "0x8"
                    }
                ]
            },
            {
                "isFinalized": false,
                "startBlockNumber": "0x1554",
                "topElectingNodes": []
            }
        ]
    },
    "id": 1
}

pos_getBlockByHash

Get block information by its hash value

Parameters

HASH: the hash value of the block

params: [
  "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"
]

Returns

epoch: QUANTITY - the epoch that the block is in
hash: HASH - the hash value of the block
height: QUANTITY - the block height
miner: [ADDRESS] - block creator, can be null
nextTxNumber: QUANTITY - the number of the next transaction
parentHash: HASH - the hash value of the parent block
pivotDecision: Decision - the decision to PoW chain
round: QUANTITY - current round
signatures: Array of Signature - the signatures of the block
timestamp: QUANTITY - the timestamp of the block

Signature

区块签名信息

account: ADDRESS - the account address of the signature
votes: QUANTITY - the number of votes of the signing account

Example

Request

curl --location --request POST 'http://localhost:12537' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "pos_getBlockByHash",
    "params": ["0x2b8b9d33e79e1735817a1278a9c8c5be828101b281bd4190531686153bee317b"]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "epoch": "0x5a",
        "hash": "0x2b8b9d33e79e1735817a1278a9c8c5be828101b281bd4190531686153bee317b",
        "height": "0x14ef",
        "miner": "0x046ca462890f25ed9394ca9f92c979ff48e1738a81822ecab96d83813c1a433c",
        "nextTxNumber": "0x1da7",
        "parentHash": "0x89cf3089296679dfef822d3dca037decab2a301de6f047e56c69cb34ae0b79e2",
        "pivotDecision": {
          "height": "0x113af0",
          "blockHash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"
        },
        "round": "0x13",
        "signatures": [
            {
                "account": "0x046ca462890f25ed9394ca9f92c979ff48e1738a81822ecab96d83813c1a433c",
                "votes": "0xc8"
            },
            {
                "account": "0x459b19e745eb410c3696ff1ed15f9de9bb46aa5fefc27b0b6e8b8d7aaadfe8c0",
                "votes": "0x32"
            }
        ],
        "timestamp": "0x5cce0e869522a"
    },
    "id": 1
}

pos_getBlockByNumber

Get block information by its block number

Parameters

QUANTITY|TAG: block number or block TAG（latest_committed, latest_voted）

Returns

the same as pos_getBlockByHash

Example

Request

curl --location --request POST 'http://localhost:12537' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "pos_getBlockByNumber",
    "params": ["0x14ef"]
}'

pos_getRewardsByEpoch

returns the rewards information of a PoS epoch

Parameters

QUANTITY: epoch number

params: [
  "0x4a"
]

Returns

accountRewards: Array of AccountReward
powEpochHash: HASH - the hash value of the PoW block when the rewards are made

AccountReward

posAddress: ADDRESS - PoS account address
powAddress: BASE32 - PoW account address
reward: QUANTITY - the number of rewards, in the unit of Drip

Example

Request

curl --location --request POST 'http://localhost:12537' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "pos_getRewardsByEpoch",
    "params": ["0x4a"]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "accountRewards": [
            {
                "posAddress": "0x459b19e745eb410c3696ff1ed15f9de9bb46aa5fefc27b0b6e8b8d7aaadfe8c0",
                "powAddress": "NET8888:TYPE.USER:AAKSNR7XKKFFAM17MNESKAGU076T8FAG3YJ6PTHN16",
                "reward": "0x14931d20aa21eae3e6f"
            },
            {
                "posAddress": "0x046ca462890f25ed9394ca9f92c979ff48e1738a81822ecab96d83813c1a433c",
                "powAddress": "NET8888:TYPE.USER:AAPXUPNXG96GZ4077DAV0151K7P8498N9A6DMAWK1N",
                "reward": "0x2d49549e023888cd390"
            }
        ],
        "powEpochHash": "0x361cb0f19fd13c30da467d20a84ef01aabcd55e9812c5e2fd0721ea11a52e9f1"
    },
    "id": 1
}

pos_getTransactionByNumber

Get the transaction information by transaction number

Parameters

QUANTITY: transaction number

params: [
  "0x4a"
]

Returns

the transaction information

hash: HASH - the hash value of the transaction
from: ADDRESS - the address of the sender
number: QUANTITY - transaction number
blockHash: [HASH] - the hash value of the block that the transaction belongs to
blockNumber: [QUANTITY] - the block number of the block that the transaction belongs to
payload: [OBJECT] - information of the transaction. The content of the payload differs with different transaction types.
status: [ENUM] - the status of the transaction. Possible values are Executed, Failed, Discard
timestamp: [QUANTITY] - the timestamp of the transaction
type: ENUM the type of the transaction. Possible values are BlockMetadata, Election, Retire, Register, UpdateVotingPower, PivoteDecision, Dispute, Other

There are six types of payload（the payload of BlockMetadata transactions is null）:

Register:

vrfPublicKey: STRING - the VRF public key
publicKey: STRING - the public key

{
  "publicKey": "0x90901cc921cd86c6a67bdb7652a3dc4e03e069c6ef6d8294eb4e856e396bb10e2191996a914eaaa9dfdaa75f2a3d70a3",
  "vrfPublicKey": "0x02a0c4e36a2e9a3a2804486b7c849d0eb6f30094e3fe91a9015e9c16f9279fbff8"
}

Election:

publicKey: STRING - the public key
targetTerm: QUANTITY - the committee number under election (epoch)
vrfProof: STRING - the VRF proof
vrfPublicKey: STRING - the VRF public key

{
  "publicKey": "0x8abc04b696da9699601c595cf3a9539e657262d42eef6b63fb324bb5b987418bf5491b04ed21edce4296174cb6d95fcc",
  "targetTerm": "0x7",
  "vrfProof": "0x03c09bec671c32ca143f67f3f965cf913993a53cc268f12954649d54548afe70e75c87fda23fbd01cd9e4af184aa06af01adfa0fce92697e811635190935cecf48aca9804a12e604df6f19455d1ca59f4f",
  "vrfPublicKey": "0x03862bbe4b6591457ebf5d410ab12fe8e9bebe80171a8d2f73db45c5933a8173a4"
}

UpdateVotingPower:

address: HASH - PoS account address
votingPower: QUANTITY - the number of increased votes

{
  "address": "0x52893f0ecd91f68b7db8a6eb04eb888b5ca1b208009eb9dfb434ad5da372f6f2",
  "votingPower": "0xb"
}

Retire:

address: HASH - PoS account address
votingPower: QUANTITY - the number of retired votes

{
  "address": "c70a93136ddff3023c4c5244c2be9141d242cdcb11d7ed15c053728c959b87bc",
  "votingPower": "0xa"
}

PivotDecision:

height: QUANTITY - the height of the pivot decision
blockHash: HASH - the hash value of the pivot decision

{
  "blockHash": "0x0abf7b384d8bb02a98f21d1582e6d465b1e2382978d5473cbceb473039b0eef3",
  "height": "0x2900"
}

Dispute:

address: HASH - account address
blsPublicKey: STRING - the BLS public key
vrfPublicKey: STRING - the VRF public key
conflictingVotes: ConflictingVotes - information of the conflicting votes

The structure of ConflictingVotes is shown as below:

conflictVoteType: STRING - the type of the conflict vote. Possible values are proposal, vote
first: STRING - the first vote
second: STRING - the second vote

Example

Request

curl --location --request POST 'http://localhost:12537' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "pos_getTransactionByNumber",
    "params": ["0x71"]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "blockHash": "0x355497700fc4c530c4eefa47c90deb052baaba4950934dfa6143f3c7321f3df1",
        "blockNumber": "0x3a",
        "from": "0x6f2e774cb8b83957d29e6a0b06551c11e632e1a0f46bee0d82b2fdc2b82fe4f9",
        "hash": "0x5505191e2f783e141fb8c84193829e494a27f197840987821514a12a0e04a10c",
        "number": "0x71",
        "payload": {
            "blockHash": "0xd66e1d6050d7070cab189a524782381e211508fa204a0674ea35fa1523cfba90",
            "height": "0x129"
        },
        "status": "Executed",
        "timestamp": "0x5cd05bea6a9b0",
        "type": "PivotDecision"
    },
    "id": 1
}

More Info

Common Errors
Harfork height