PoS RPC

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

conflux-rust introduced the PoS finality mechanism from v2.0.0 to speed up the finality of blocks, thereby preventing 51% attacks. The PoS finality mechanism will introduce an independent PoS chain to achieve PoS consensus and finalize PoW blocks. The corresponding PoS also has its own special RPC method for obtaining the data of the PoS chain.

Currently, only the archive node of conflux-rust can provide PoS RPC services to the outside world, and RPC needs to be configured with the public_rpc_apis option to enable it.

pos group can be added to the currently opened RPC method group.

public_rpc_apis = "safe,pos"

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

public_rpc_apis = "all"

basic concepts

epoch

PoS also has the concept of epoch, which can be understood as an epoch. But it is not the same as PoW's epoch concept. An epoch represents the term of a committee member, 1 . Each epoch corresponds to one hour. After each epoch, some committees in the committee are replaced. Rewards for participating in PoS consensus are also distributed according to epoch.

round

The Chinese translation of round rounds, and the PoS chain will per minute on average, that is, try to generate a PoS block. That is, each epoch will have 60 rounds, and every new epoch, the round will start again from 1 .

Note: Not every round will produce a block, and it may fail to produce a block due to network or consensus failure.

block.number

block.number is the height of the block. Every time a new block is generated, the number will increase by one.

After the PoS block is proposed by a committee member, it will be sent to the network for voting. When the block collects enough votes, the voting is successful voted , but the block has not been committed yet. After the block is generated, the block corresponding to the initial round will be submitted, and the status will become committed.

pivotDecision

pivotDecision is the final decision of the PoS chain on the PoW chain block. Once a PoW block is referenced by PoS, it means that the PoW block has been finalized and no revert will occur. The block of the PoS chain will contain the PivotDecision information, indicating that the PoS block has finalized a block of the PoW main chain. The pivotDecision information is the number or hash of a block in the PoW main chain.

PoS Address

The PoS account address is a 256-bit hash value different from the PoW address format, for example:

0x046ca462890f25ed9394ca9f92c979ff48e1738a81822ecab96d83813c1a433c

PoS Model

AccountStatus

After an account registers to participate in the PoS consensus, or votes to increase the pledge, the number of votes will first enter the inQueue state, and after seven days, it will become the locked state.
After the user initiates the unlocking operation, the ticket to be unlocked will first enter the outQueue state, and it will also take seven days to change to the unlocked state.

• availableVotes : QUANTITY - the number of votes currently available for the account, equal to sum inQueue + locked
• forfeited : QUANTITY - When the account is detected to be malicious, the staked votes will be locked and cannot be withdrawn
• forceRetired : [ QUANTITY ] - Number of blocks when the account was forced to retire
• inQueue : Array of VotesInQueue - the queue currently waiting for a lock
• locked : QUANTITY - the number of votes the account is currently locked
• outQueue : Array of VotesInQueue - Queue currently waiting to be unlocked
• unlocked : QUANTITY - The total number of votes unlocked in the account history

Decision

The PoS chain determines the height of the PoW main chain, and the determined PoW block is the Finalized block

• height : QUANTITY - Spindle block height
• blockHash : HASH - Spindle block hash

VotesInQueue

User is waiting to lock or to unlock ticket information.

• endBlockNumber : QUANTITY - the block number at the end of the state
• power : QUANTITY - number of tickets in current status

RPCs

pos_getStatus

Returns the current state information of the PoS chain.

Parameters

Empty

Returns

Object - PoS status object.

• epoch : QUANTITY - The current epoch of the PoS chain
• latestCommitted : QUANTITY - the latest committed block number, the committed block will no longer be reverted
• latestVoted : [ QUANTITY ] - The most recent block number that was successfully voted on. If the block that has not yet completed voting is null
• pivotDecision : Decision decision of the latest PoW chain finalized by the current PoS chain

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 PoS account information

Parameters

1. ADDRESS : 32 Bytes - PoS account address
2.[ QUANTITY ]: optional block number, used to query 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 - Account Address
• blockNumber : QUANTITY - the block number corresponding to the state
• status : OBJECT - User's current status information object, see Account Status

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

The current PoS committee information is obtained by default, or the committee information of a block in history can be obtained by specifying blockNumber.

Parameters

1.[ QUANTITY ]: optional block number, used to query the committee information of a certain block height

Returns

• currentCommittee : OBJECT - Current Committee Member, see CurrentCommittee
• elections : Array - Persons who are running for election

CurrentCommittee

Current Committee Information

• epochNumber : QUANTITY - epoch number of committee term
• nodes : Array of CommitteNode - List of committee members
• quorumVotingPower : QUANTITY - Minimum number of votes required for block voting to reach consensus
• totalVotingPower : QUANTITY - the total number of votes for the current committee

CommitteNode

Committee Information

• address : ADDRESS - Account Address
• votingPower : QUANTITY - votes

Election

• isFinalized : BOOLEAN - Whether this round of elections has been determined
• startBlockNumber : QUANTITY - starting block number
• topElectingNodes : Array of CommitteNode - for top 50 users

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 based on hash

Parameters

1. HASH : block hash

params: [
  "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"
]

Returns

• epoch : QUANTITY - the epoch of the block
• hash : HASH - block hash
• height : QUANTITY - block height
• miner : [ ADDRESS ] - the creator of the block, possibly null
• nextTxNumber : QUANTITY - the actual number of the next block transaction
• parentHash : HASH - parent block hash
• pivotDecision : Decision - Decision on PoW spindle chain
• round : QUANTITY - current round
• signatures : Array of Signature - Signature information for the block
• timestamp : QUANTITY - Timestamp

Signature

block signature information

• account : ADDRESS - signed account address
• votes : QUANTITY - votes for signed accounts

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 based on block number

Parameters

1. QUANTITY|TAG : block number or block TAG ( latest_committed , latest_voted )

Returns

as pos_getBlockByHash 161d79eaf7642a

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 specific information of a PoS epoch to issue rewards

Parameters

1. QUANTITY : epoch number

params: [
  "0x4a"
]

Returns

• accountRewards: Array of AccountReward
• powEpochHash : HASH - the hash of the PoW chain spindle block when the reward is issued

AccountReward

• posAddress : ADDRESS - PoS account address
• powAddress : BASE32 - PoW account address
• reward : QUANTITY - Amount of reward received in 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 transaction information based on transaction number

Parameters

1. QUANTITY : transaction number

params: [
  "0x4a"
]

Returns

Transaction Details

• hash : HASH - transaction hash
• from : ADDRESS - sender address
• number : QUANTITY - transaction number
• blockHash : [ HASH ] - The hash of the block the transaction belongs to
• blockNumber : [ QUANTITY ] - The block code to which the transaction belongs
• payload : [ OBJECT ] - Main transaction data, payload content varies according to transaction type
• status : [ ENUM ] - Status of the transaction, possible values: Executed , Failed , Discard
• timestamp : [ QUANTITY ] - Transaction timestamp
• type : ENUM type of transaction, possible values: BlockMetadata , Election , Retire , Register , UpdateVotingPower , PivoteDecision , Dispute , Other

There are six types of payloads (the transaction payload of BlockMetadata type is null):

Register: Register

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

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

Election: Election

• publicKey: STRING - public key
• targetTerm: QUANTITY - the committee number (epoch) to which the candidate is planned to run
• vrfProof: STRING - VRF Proof
• vrfPublicKey: STRING - VRF public key

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

UpdateVotingPower: Added voting transactions

• address: HASH - PoS account address
• votingPower: QUANTITY - increased votes

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

Retire: Retirement Vote

• address: HASH - PoS account address
• votingPower: QUANTITY - votes for retirement

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

PivotDecision: Pivot block decision

• height: QUANTITY - PoS to PoW spindle height
• blockHash: HASH - PoS to PoW spindle decision hash

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

Dispute: Dispute

• address: HASH - account address
• blsPublicKey: STRING - BLS public key
• vrfPublicKey: STRING - VRF public key
• conflictingVotes: ConflictingVotes - conflicting voting information

The ConflictingVotes structure is as follows:

• conflictVoteType: STRING - The possible values of the dispute type are proposal , vote
• first: STRING - first vote
• second: STRING - 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
}

Related Articles:

• Conflux Development Kit
• conflux-chain github
• conflux-fans github