Essential qPoS RPC Commands and Their Implementation

In today’s development update, I document the 12 essential RPC (remote procedure calls) required for users to purchase and modify stakers. These commands comprise the full set of commands necessary to query and interact with qPoS stakers and the qPoS ledger (collectively known as the “registry”).

My work this week represented my final coding push before building and testing the qPoS client. With these RPC commands, the current state of the qPoS code can be considered a complete, albeit very rough codebase. Of course it still needs plenty of organizing, debugging, and likely some new coding before the qPoS is minimally functional. However, I feel like I have hit a significant milestone on the way to qPoS, and am entering a new, phase of development characterized by improving code I have already written.

–––––

Overview of the qPoS RPC Commands

I will preface documenting the commands by reviewing the structure of those commands that affect changes in the registry. The simplest of these commands, both in terms of syntax and functionality is called enablestaker. This command ensures that a staker is enabled to sign blocks, rather than sit dormantly, neither earning rewards nor getting penalized for missing blocks. They syntax of the “enablestaker” command is

enablestaker <txid> <vout> <alias>

The three arguments (“txid”, “vout”, and “alias”) are common to every RPC command that affects changes to the registry. The easiest argument to understand is “alias”, which specifies a staker by the name given to it upon registration. I have described aliases in a previous post, but basically aliases are 3–16 character names that (1) are composed of only numbers and letters, (2) start with a letter, (3) are case sensitive for representation (as when displaying a staker’s info on a web page), and (4) are not case sensitive for identification (as when using RPC commands).

The other two arguments, “txid” and “vout” specify what is known as an “unspent transaction output” (UTXOs), which is a single amount of unspent funds. I have described the UTXO model elsewhere, most recently here in the context of the non-hierarchical nature of the blockchain data structure. The “txid” is the transaction ID, and “vout” is the index of a specific output within this transaction that will be spent in the new transaction.

The specification of a UTXO serves three purposes: (1) it identifies a source of funds for transaction fees or for a purchase (as when buying a staker) and (2) by signing the UTXO, the user proves that they have the authority to execute the change to the registry. In some cases, as when claiming funds, (3) the specified UTXO also serves to identify the claimant. While the need for funds is clear, how spending a UTXO authorizes a state transition or serves as identification is less obvious.

The following figure shows a hypothetical bank draft (“cheque”) that is signed by Satoshi Nakamoto. Notice that the cheque itself (1) provides identification on the “Remit To:” line (light green arrow) and also (2) proves authorization on the signature line (dark blue arrow). The cheque has the text “The undersigned hereby transfers the value of this UTXO to the affixed new Outputs”, which means that the signature marks this cheque for 100 XST spent so that it can not be spent again (“double-spent”). Additionally new cheques, affixed to the spent cheque, will total 100 XST minus any transaction fees.

One important property of spent outputs is that it is possible to use their identification and authorization properties to execute a command on behalf of the spender, as illustrated in the following figure:

Anyone who executes the “Enable Staker #1” command on their own client in response to this order can verify that Staker #1 belongs to Satoshi Nakamoto, and that the signature is genuine (using public-private key cryptography). Notice that the command is also an output, but it has no value and cannot be spent (“non-spendable”).

–––––

Documenting The qPoS RPC Commands

The remainder of today’s post explains the usage and function of the qPoS RPC commands, starting first with informational commands, then describing commands that direct changes to the registry. Mandatory literals are bare words (e.g. the command names), mandatory arguments are in angled brackets, and optional arguments are in square brackets. All commands return valid JSON.

Informational qPoS RPC Commands

getstakerprice: Returns the staker price at the moment of the call. Stakers go up in price with every block (albeit ever so slightly). Because of these price increases, this query should be for informational purposes, such as selecting or creating an input (unspent output, or UTXO) with which to purchase a staker. The “purchasestaker” RPC command (described below) will automatically determine the bidding price for a staker, attempting to account for any marginal increases in staker prices between constructing the transaction and its acceptance to the blockchain. Syntax:
getstakerprice
getstakerid: Returns the staker ID for the alias provided. This command offers simple accessibility to a staker’s ID for services that need to navigate the exhaustive output of “getqposinfo”, described below. Syntax:
getstakerid <alias>
getstakerinfo: Returns complete information about a staker, including id, version, enabled status, weight, permission keys (owner, delegate, controller), total earned, blocks produced and missed, and recent history of block production, among other information. Syntax:
getstakerinfo <alias>
getqposbalance: Returns the qPoS ledger balance for a public key. This command is useful to claim balances using the “claimqposbalance” RPC command.
getqposbalance <pubkey>
getqposinfo: Returns exhaustive info for all stakers, the queue, and ledger balances, and public keys therein. If another RPC doesn’t have the info needed, “getqposinfo” does. This command is useful for websites offering informational or other services that rely on knowing the current state of the qPoS registry at any moment. Syntax:
getqposinfo

Commands that Affect the Registry

All commands that affect the registry require the specification of a UTXO using the “txid” and “vout” arguments. With the exception of “purchasestaker”, the signing of this UTXO serves to authorize the state changes. The “purchasestaker” command also requires specifying a UTXO as a source of funds. This requirement is to encourage users to select inputs carefully (to obscure relationships with other funds), and also to retain consistency with other RPC commands. Any change is returned to the owner of the specified UTXO (i.e. the caller of the RPC command).

purchasestaker: Purchases a staker and assigns the owner, controller, and delegate keys as specified. The bid can either be set manually using the optional “amount” argument, or automatically. Automatic bid selection includes a small addition that accounts for any price increases between submitting the command and its inclusion in the blockchain. This addition is expected to be a small fraction of 1 XST. If the delegate key is specified, a delegate payout, expressed as a percentage of block earnings, must also be specified. Payout is rounded to thousands of a percent. Note that either zero or all three of the “delegate”, “controller”, and “payout” arguments must be provided. In other words, if the caller specifies a delegate, the caller must also specify the controller and payout. Syntax:
purchasestaker <txid> <vout> <alias> <owner> [amount]
[delegate controller payout]
setstakerowner: Sets the staker owner key. This command transfers ownership! To help avoid unintended ownership transfers, users of this command must type the literal “iunderstand” at the end of the command. Syntax:
setstakerowner <txid> <vout> <alias> <owner> iunderstand
setstakerdelegate: Sets the staker delegate key. Note that the payout, expressed in percentage must be provided. Delegation is described here. Syntax:
setstakerdelegate <txid> <vout> <alias> <delegate>
<payout>
setstakercontroller: Sets the staker controller key. A controller is authorized to enable and disable stakers, described here. Syntax:
setstakercontroller <txid> <vout> <alias> <controller>
enablestaker: Ensures that the staker is enabled. This command can be submitted to the blockchain even if a staker is already enabled. In such a case, no change to the staker will occur. Syntax:
enablestaker <txid> <vout> <alias>
disablestaker: Ensures that the staker is disabled. Similar to “enablestaker”, “disablestaker” can be submitted to the blockchain even if the staker is already disabled. Syntax:
disablestaker <txid> <vout> <alias>
claimqposbalance: This command claims qPoS block rewards that are tracked in the registry ledger. To make these rewards generally transferable they must be claimed, but no more frequently than once a day for any given claimant (owner of the balance). Claims will be sent to the owner of the balance, as identified by the specified UTXO (by the “txid” and “vout” arguments). Because the UTXO identifies the claimant, the public key of the claimant is not a required (or even possible) argument to “claimqposbalance”. How UTXOs are used for identification and authorization is described above. The amount claimed must also be specified, and of course must not exceed the claimant’s registry balance. Syntax:
claimqposbalance <txid> <vout> <amount>