From c4e7561a7dab0d28f14c771881ef883af45f197c Mon Sep 17 00:00:00 2001 From: Tasos Bitsios Date: Thu, 24 Oct 2024 14:03:24 +0200 Subject: [PATCH 1/2] arc78: add scope section. Mark fields with required. Example of keyreg offline --- ARCs/arc-0078.md | 68 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 55 insertions(+), 13 deletions(-) diff --git a/ARCs/arc-0078.md b/ARCs/arc-0078.md index 1a9fbd3f2..92e6999c3 100644 --- a/ARCs/arc-0078.md +++ b/ARCs/arc-0078.md @@ -25,6 +25,22 @@ As in [ARC-26](./arc-0026.md), URIs follow the general format for URIs as set fo Elements of the query component may contain characters outside the valid range. These are encoded differently depending on their expected character set. The text components (note, xnote) must first be encoded according to UTF-8, and then each octet of the corresponding UTF-8 sequence must be percent-encoded as described in RFC 3986. The binary components (votekey, selkey, etc.) must be encoded with base64url as specified in RFC 4648 section 5. +### Scope + +This ARC explicitly supports the two major subtypes of key registration transactions: + +- Online keyreg transcation + - Declares intent to participate in consensus and configures required keys +- Offline keyreg transaction + - Declares intent to stop participating in consensus + +The following variants of keyreg transactions are not defined: + +- Non-participating keyreg transcation + - This transaction subtype is considered deprecated +- Heartbeat keyreg transaction + - This transaction subtype will be included in the future block incentives protocol. The protocol specifies that this transaction type must be submitted by a node in response to a programmatic "liveness challenge". It is not meant to be signed or submitted by an end user. + ### ABNF Grammar ``` @@ -53,27 +69,27 @@ As in the base [ARC-26](./arc-0026.md) standard, the scheme component ("algorand ### Query Keys -- address: Algorand address of transaction sender +- address: Algorand address of transaction sender. Required. -- type: fixed to "keyreg". Used to disambiguate the transaction type from the base [ARC-26](./arc-0026.md) standard and other possible extensions +- type: fixed to "keyreg". Used to disambiguate the transaction type from the base [ARC-26](./arc-0026.md) standard and other possible extensions. Required. -- votekeyparam: The vote key parameter to use in the transaction. Encoded with base64url encoding. +- votekeyparam: The vote key parameter to use in the transaction. Encoded with base64url encoding. Required for keyreg online transactions. -- selkeyparam: The selection key parameter to use in the transaction. Encoded with base64url encoding. +- selkeyparam: The selection key parameter to use in the transaction. Encoded with base64url encoding. Required for keyreg online transactions. -- sprfkeyparam: The state proof key parameter to use in the transaction. Encoded with base64url encoding. +- sprfkeyparam: The state proof key parameter to use in the transaction. Encoded with base64url encoding. Required for keyreg online transactions. -- votefstparam: The first round valid parameter to use in the transaction. +- votefstparam: The first round on which the voting keys will valid. Required for keyreg online transactions. -- votelstparam: The last round valid parameter to use in the transaction. +- votelstparam: The last round on which the voting keys will be valid. Required for keyreg online transactions. -- votekdparam: The key dilution key parameter to use in the transaction. +- votekdparam: The key dilution key parameter to use. Required for keyreg online transactions. -- xnote: As in [ARC-26](./arc-0026.md). A URL-encoded notes field value that must not be modifiable by the user when displayed to users. +- xnote: As in [ARC-26](./arc-0026.md). A URL-encoded notes field value that must not be modifiable by the user when displayed to users. Optional. -- note: As in [ARC-26](./arc-0026.md). A URL-encoded default notes field value that the the user interface may optionally make editable by the user. +- note: As in [ARC-26](./arc-0026.md). A URL-encoded default notes field value that the the user interface may optionally make editable by the user. Optional. -- fee: Optional. A static fee to set for the transaction in microAlgos. Useful to signal intent to receive participation incentives (e.g. with a 2,000,000 microAlgo transaction fee.) +- fee: Optional. A static fee to set for the transaction in microAlgos. Useful to signal intent to receive participation incentives (e.g. with a 2,000,000 microAlgo transaction fee.) Optional. - (others): optional, for future extensions @@ -81,7 +97,7 @@ As in the base [ARC-26](./arc-0026.md) standard, the scheme component ("algorand This section contains encoding examples. The raw transaction object is presented along with the resulting [ARC-78](./arc-0078.md) URI encoding. -#### Encoding with minimum fee +#### Encoding keyreg online transactioon with minimum fee The following raw keyreg transaction: @@ -123,7 +139,33 @@ Note the difference between base64 encoding in the raw object and base64url enco Note: Here, the fee is omitted from the URI (due to being set to the minimum 1,000 microAlgos.) When the fee is omitted, it is left up to the application or wallet to decide. This is for demonstrative purposes - the ARC-78 standard does not require this behavior. -#### Encoding with custom fee and note +#### Encoding keyreg offline transactioon + +The following raw keyreg transaction: + +``` +{ + "txn": { + "fee": 1000, + "fv": 1776240, + "gh:b64": "kUt08LxeVAAGHnh4JoAoAMM9ql/hBwSoiFtlnKNeOxA=", + "lv": 1777240, + "snd:b64": "+gJAXOr2rkSCdPQ5DEBDLjn+iIptzLxB3oSMJdWMVyQ=", + "type": "keyreg" + } +} +``` + +Will result in this ARC-78 encoded URI: + +``` +algorand://7IBEAXHK62XEJATU6Q4QYQCDFY475CEKNXGLYQO6QSGCLVMMK4SLVTYLMY?type=keyreg +``` + +This offline keyreg transaction encoding is the smallest compatible ARC-78 representation. + + +#### Encoding keyreg online transactioon with custom fee and note The following raw keyreg transaction: From 0ebc4c0cad5fbcf3cf1701abc5dedb79d9639fcd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane?= Date: Fri, 15 Nov 2024 09:34:08 +0100 Subject: [PATCH 2/2] Update to Final before merge --- ARCs/arc-0078.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/ARCs/arc-0078.md b/ARCs/arc-0078.md index 92e6999c3..2984ad690 100644 --- a/ARCs/arc-0078.md +++ b/ARCs/arc-0078.md @@ -1,11 +1,10 @@ --- arc: 78 -title: URI scheme, keyreg extension +title: URI scheme, keyreg Transactions extension description: A specification for encoding Key Registration Transactions in a URI format. author: Tasos Bitsios (@tasosbit) discussions-to: https://github.com/algorandfoundation/ARCs/issues/314 -status: Last Call -last-call-deadline: 2024-10-15 +status: Final type: Standards Track category: Interface sub-category: General @@ -85,7 +84,7 @@ As in the base [ARC-26](./arc-0026.md) standard, the scheme component ("algorand - votekdparam: The key dilution key parameter to use. Required for keyreg online transactions. -- xnote: As in [ARC-26](./arc-0026.md). A URL-encoded notes field value that must not be modifiable by the user when displayed to users. Optional. +- xnote: As in [ARC-26](./arc-0026.md). A URL-encoded notes field value that must not be modifiable by the user when displayed to users. Optional. - note: As in [ARC-26](./arc-0026.md). A URL-encoded default notes field value that the the user interface may optionally make editable by the user. Optional.