pos Namespace

conflux-rust introduces the PoS finality starting from v2.0.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 block number when the votes was retired
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 users total unlocked votes in history

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.

参数

Empty

返回值

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.

示例

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

参数

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"
]

返回值

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

示例

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.

参数

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

返回值

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

示例

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

参数

HASH: the hash value of the block

params: [
  "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"
]

返回值

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
lastTxNumber: QUANTITY - the number of the current block's last 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

Block signature info

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

示例

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",
        "lastTxNumber": "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

参数

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

返回值

the same as pos_getBlockByHash

示例

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

参数

QUANTITY: epoch number

params: [
  "0x4a"
]

返回值

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

示例

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

参数

QUANTITY: transaction number

params: [
  "0x4a"
]

返回值

交易详情

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）:

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

示例

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
}

Basic Concepts​

epoch​

round​

block.number​

pivotDecision​

PoS Address​

PoS Model​

AccountStatus​

Decision​

VotesInQueue​

RPCs​

pos_getStatus​

参数​

返回值​

示例​

pos_getAccount​

参数​

返回值​

示例​

pos_getCommittee​

参数​

返回值​

CurrentCommittee​

CommitteNode​

Election​

示例​

pos_getBlockByHash​

参数​

返回值​

Signature​

示例​

pos_getBlockByNumber​

参数​

返回值​

示例​

pos_getRewardsByEpoch​

参数​

返回值​

AccountReward​

示例​

pos_getTransactionByNumber​

参数​

返回值​

示例​

Basic Concepts

epoch

round

block.number

pivotDecision

PoS Address

PoS Model

AccountStatus

Decision

VotesInQueue

RPCs

pos_getStatus

参数

返回值

示例

pos_getAccount

参数

返回值

示例

pos_getCommittee

参数

返回值

CurrentCommittee

CommitteNode

Election

示例

pos_getBlockByHash

参数

返回值

Signature

示例

pos_getBlockByNumber

参数

返回值

示例

pos_getRewardsByEpoch

参数

返回值

AccountReward

示例

pos_getTransactionByNumber

参数

返回值

示例