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 half 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 30 seconds (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 13 days. When the user makes an unlock command, the votes to be unlocked will first go into the outQueue state. Then it takes 1 day 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.

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

1. ADDRESS: 32 Bytes - PoS account address
2. [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

1. [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

1. 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
• 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

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

Parameters

1. 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

1. 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

1. QUANTITY: transaction number

params: [
  "0x4a"
]

Returns

交易详情

• 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
}