From 1dd146cc58e7734b2d5140af72aedb6aceb0a5dc Mon Sep 17 00:00:00 2001 From: Tasos Bitsios Date: Mon, 7 Oct 2024 10:20:50 +0200 Subject: [PATCH 1/7] arc26k --- ARCs/arc-0026-k.md | 176 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 ARCs/arc-0026-k.md diff --git a/ARCs/arc-0026-k.md b/ARCs/arc-0026-k.md new file mode 100644 index 000000000..6baf82cc5 --- /dev/null +++ b/ARCs/arc-0026-k.md @@ -0,0 +1,176 @@ +--- +arc: 26-k +title: URI scheme, keyreg extension +description: A specification for encoding Key Registration Transactions in a URI format. +author: Tasos Bitsios (@tasosbit) +status: Draft +type: Standards Track +category: Interface +sub-category: General +created: 2024-10-02 +--- + +## Abstract + +This URI specification represents an extension to the base Algorand URI encoding standard (ARC-26) that specifies encoding of consensus participation key registration transactions through deeplinks, QR codes, etc. + +## Specification + +### General format + +As in ARC-26, URIs follow the general format for URIs as set forth in RFC 3986. The path component consists of an Algorand address, and the query component provides additional transaction parameters. + +Elements of the query component may contain characters outside the valid range. These 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. + +### ABNF Grammar + +``` +algorandurn = "algorand://" algorandaddress [ "?" keyregparams ] +algorandaddress = *base32 +keyregparams = keyregparam [ "&" keyregparams ] +keyregparam = [ typeparam / votekeyparam / selkeyparam / sprfkeyparam / votefstparam / votelstparam / votekdparam / noteparam / feeparam / otherparam ] +typeparam = "type=keyref" +votekeyparam = "votekey=" *qbase64url +selkeyparam = "selkey=" *qbase64url +sprfkeyparam = "sprfkey=" *qbase64url +votefstparam = "votefst=" *qdigit +votelstparam = "votelst=" *qdigit +votekdparam = "votekdkey=" *qdigit +noteparam = (xnote | note) +xnote = "xnote=" *qchar +note = "note=" *qchar +fee = "fee=" *qdigit +otherparam = qchar *qchar [ "=" *qchar ] +``` + +- "qbase64url" corresponds to valid characters of "base64url" encoding, as defined in [RFC 4648 section 5](https://www.rfc-editor.org/rfc/rfc4648.html#section-5) +- "qchar" corresponds to valid characters of an RFC 3986 URI query component, excluding the "=" and "&" characters, which this specification takes as separators. + +As in the base ARC-26 standard, the scheme component ("algorand:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The rest of the URI is case-sensitive, including the query parameter keys. + +### Query Keys + +- address: Algorand address of transaction sender + +- type: fixed to "keyreg". Used to disambiguate the transaction type from the base ARC-26 standard and other possible extensions + +- votekeyparam: The vote key parameter to use in the transaction. Encoded with [base64url](https://www.rfc-editor.org/rfc/rfc4648.html#section-5) encoding. + +- selkeyparam: The selection key parameter to use in the transaction. Encoded with [base64url](https://www.rfc-editor.org/rfc/rfc4648.html#section-5) encoding. + +- sprfkeyparam: The state proof key parameter to use in the transaction. Encoded with [base64url](https://www.rfc-editor.org/rfc/rfc4648.html#section-5) encoding. + +- votefstparam: The first round valid parameter to use in the transaction. + +- votelstparam: The last round valid parameter to use in the transaction. + +- votekdparam: The key dilution key parameter to use in the transaction. + +- xnote: As in ARC-26. A URL-encoded notes field value that must not be modifiable by the user when displayed to users. + +- note: As in ARC-26. A URL-encoded default notes field value that the the user interface may optionally make editable by the user. + +- 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.) + +- (others): optional, for future extensions + +### Appendix + +This section contains encoding examples. The raw transaction object is presented along with the resulting arc26k URI encoding. + +#### Encoding with minimum fee + +The following raw keyreg transaction: + +``` +{ + "txn": { + "fee": 1000, + "fv": 1345, + "gh:b64": "kUt08LxeVAAGHnh4JoAoAMM9ql/hBwSoiFtlnKNeOxA=", + "lv": 2345, + "selkey:b64": "+lfw+Y04lTnllJfncgMjXuAePe8i8YyVeoR9c1Xi78c=", + "snd:b64": "+gJAXOr2rkSCdPQ5DEBDLjn+iIptzLxB3oSMJdWMVyQ=", + "sprfkey:b64": "3NoXc2sEWlvQZ7XIrwVJjgjM30ndhvwGgcqwKugk1u5W/iy/JITXrykuy0hUvAxbVv0njOgBPtGFsFif3yLJpg==", + "type": "keyreg", + "votefst": 1300, + "votekd": 100, + "votekey:b64": "UU8zLMrFVfZPnzbnL6ThAArXFsznV3TvFVAun2ONcEI=", + "votelst": 11300 + } +} +``` + +Will result in this ARC-26-K encoded URI: + +``` +algorand://7IBEAXHK62XEJATU6Q4QYQCDFY475CEKNXGLYQO6QSGCLVMMK4SLVTYLMY? +type=keyreg +&selkey=-lfw-Y04lTnllJfncgMjXuAePe8i8YyVeoR9c1Xi78c +&sprfkey=3NoXc2sEWlvQZ7XIrwVJjgjM30ndhvwGgcqwKugk1u5W_iy_JITXrykuy0hUvAxbVv0njOgBPtGFsFif3yLJpg +&votefst=1300 +&votekd=100 +&votekey=UU8zLMrFVfZPnzbnL6ThAArXFsznV3TvFVAun2ONcEI +&votelst=11300 +``` + +Note: newlines added for readability. + +Note the difference between base64 encoding in the raw object and base64url encoding in the URI parameters. For example, the selection key parameter `selkey` that begins with `+lfw+` in the raw object is encoded in base64url to `-lfw-`. + +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-26-K standard does not require this behavior. + +#### Encoding with custom fee and note + +The following raw keyreg transaction: + +``` +{ + "txn": { + "fee": 2000000, + "fv": 1345, + "gh:b64": "kUt08LxeVAAGHnh4JoAoAMM9ql/hBwSoiFtlnKNeOxA=", + "lv": 2345, + "note:b64": "Q29uc2Vuc3VzIHBhcnRpY2lwYXRpb24gZnR3", + "selkey:b64": "+lfw+Y04lTnllJfncgMjXuAePe8i8YyVeoR9c1Xi78c=", + "snd:b64": "+gJAXOr2rkSCdPQ5DEBDLjn+iIptzLxB3oSMJdWMVyQ=", + "sprfkey:b64": "3NoXc2sEWlvQZ7XIrwVJjgjM30ndhvwGgcqwKugk1u5W/iy/JITXrykuy0hUvAxbVv0njOgBPtGFsFif3yLJpg==", + "type": "keyreg", + "votefst": 1300, + "votekd": 100, + "votekey:b64": "UU8zLMrFVfZPnzbnL6ThAArXFsznV3TvFVAun2ONcEI=", + "votelst": 11300 + } +} +``` + +Will result in this ARC-26-K encoded URI: + +``` +algorand://7IBEAXHK62XEJATU6Q4QYQCDFY475CEKNXGLYQO6QSGCLVMMK4SLVTYLMY? +type=keyreg +&selkey=-lfw-Y04lTnllJfncgMjXuAePe8i8YyVeoR9c1Xi78c +&sprfkey=3NoXc2sEWlvQZ7XIrwVJjgjM30ndhvwGgcqwKugk1u5W_iy_JITXrykuy0hUvAxbVv0njOgBPtGFsFif3yLJpg +&votefst=1300 +&votekd=100 +&votekey=UU8zLMrFVfZPnzbnL6ThAArXFsznV3TvFVAun2ONcEI +&votelst=11300 +&fee=2000000 +¬e=Consensus%2Bparticipation%2Bftw +``` + +Note: newlines added for readability. + +## Rationale + +The present aims to provide a standardized way to encode key registration transactions in order to enhance the user experience of signing key registration transactions in general, and in particular in the use case of an Algorand node runner that does not have their spending keys resident on their node (as is best practice.) + +The parameter names were chosen to match the encoded key registration transaction field. + +## Security Considerations + +None. + +## Copyright + +Copyright and related rights waived via CCO. From 5d2ac31442aabfd65065ec8a2f84d98df54d6223 Mon Sep 17 00:00:00 2001 From: Tasos Bitsios Date: Mon, 7 Oct 2024 10:21:13 +0200 Subject: [PATCH 2/7] arc26k --- ARCs/arc-0026-k.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/ARCs/arc-0026-k.md b/ARCs/arc-0026-k.md index 6baf82cc5..170f84025 100644 --- a/ARCs/arc-0026-k.md +++ b/ARCs/arc-0026-k.md @@ -12,13 +12,13 @@ created: 2024-10-02 ## Abstract -This URI specification represents an extension to the base Algorand URI encoding standard (ARC-26) that specifies encoding of consensus participation key registration transactions through deeplinks, QR codes, etc. +This URI specification represents an extension to the base Algorand URI encoding standard ([ARC-26](./arc-0026.md)) that specifies encoding of key registration transactions through deeplinks, QR codes, etc. ## Specification ### General format -As in ARC-26, URIs follow the general format for URIs as set forth in RFC 3986. The path component consists of an Algorand address, and the query component provides additional transaction parameters. +As in [ARC-26](./arc-0026.md), URIs follow the general format for URIs as set forth in RFC 3986. The path component consists of an Algorand address, and the query component provides additional transaction parameters. Elements of the query component may contain characters outside the valid range. These 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. @@ -43,22 +43,22 @@ fee = "fee=" *qdigit otherparam = qchar *qchar [ "=" *qchar ] ``` -- "qbase64url" corresponds to valid characters of "base64url" encoding, as defined in [RFC 4648 section 5](https://www.rfc-editor.org/rfc/rfc4648.html#section-5) +- "qbase64url" corresponds to valid characters of "base64url" encoding, as defined in RFC 4648 section 5 - "qchar" corresponds to valid characters of an RFC 3986 URI query component, excluding the "=" and "&" characters, which this specification takes as separators. -As in the base ARC-26 standard, the scheme component ("algorand:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The rest of the URI is case-sensitive, including the query parameter keys. +As in the base [ARC-26](./arc-0026.md) standard, the scheme component ("algorand:") is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The rest of the URI is case-sensitive, including the query parameter keys. ### Query Keys - address: Algorand address of transaction sender -- type: fixed to "keyreg". Used to disambiguate the transaction type from the base ARC-26 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 -- votekeyparam: The vote key parameter to use in the transaction. Encoded with [base64url](https://www.rfc-editor.org/rfc/rfc4648.html#section-5) encoding. +- votekeyparam: The vote key parameter to use in the transaction. Encoded with base64url encoding. -- selkeyparam: The selection key parameter to use in the transaction. Encoded with [base64url](https://www.rfc-editor.org/rfc/rfc4648.html#section-5) encoding. +- selkeyparam: The selection 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](https://www.rfc-editor.org/rfc/rfc4648.html#section-5) encoding. +- sprfkeyparam: The state proof key parameter to use in the transaction. Encoded with base64url encoding. - votefstparam: The first round valid parameter to use in the transaction. @@ -66,9 +66,9 @@ As in the base ARC-26 standard, the scheme component ("algorand:") is case-insen - votekdparam: The key dilution key parameter to use in the transaction. -- xnote: As in ARC-26. 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. -- note: As in ARC-26. 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. - 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.) @@ -76,7 +76,7 @@ As in the base ARC-26 standard, the scheme component ("algorand:") is case-insen ### Appendix -This section contains encoding examples. The raw transaction object is presented along with the resulting arc26k URI encoding. +This section contains encoding examples. The raw transaction object is presented along with the resulting ARC-26-K URI encoding. #### Encoding with minimum fee From d54593b9802caf36507c6ccb7ba576a480d689a3 Mon Sep 17 00:00:00 2001 From: Tasos Bitsios Date: Mon, 7 Oct 2024 10:26:54 +0200 Subject: [PATCH 3/7] arc26k general format --- ARCs/arc-0026-k.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ARCs/arc-0026-k.md b/ARCs/arc-0026-k.md index 170f84025..aaadd5b12 100644 --- a/ARCs/arc-0026-k.md +++ b/ARCs/arc-0026-k.md @@ -20,7 +20,7 @@ This URI specification represents an extension to the base Algorand URI encoding As in [ARC-26](./arc-0026.md), URIs follow the general format for URIs as set forth in RFC 3986. The path component consists of an Algorand address, and the query component provides additional transaction parameters. -Elements of the query component may contain characters outside the valid range. These 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. +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. ### ABNF Grammar From 55e683d916645e098b6ec43f12320373c5bfa518 Mon Sep 17 00:00:00 2001 From: Tasos Bitsios Date: Mon, 7 Oct 2024 10:34:38 +0200 Subject: [PATCH 4/7] arc26k minor --- ARCs/arc-0026-k.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ARCs/arc-0026-k.md b/ARCs/arc-0026-k.md index aaadd5b12..bb6a704a9 100644 --- a/ARCs/arc-0026-k.md +++ b/ARCs/arc-0026-k.md @@ -165,7 +165,7 @@ Note: newlines added for readability. The present aims to provide a standardized way to encode key registration transactions in order to enhance the user experience of signing key registration transactions in general, and in particular in the use case of an Algorand node runner that does not have their spending keys resident on their node (as is best practice.) -The parameter names were chosen to match the encoded key registration transaction field. +The parameter names were chosen to match the corresponding names in encoded key registration transactions. ## Security Considerations From cd12b1bc4392e91888fc66a6f2c619da76f05552 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane?= Date: Tue, 15 Oct 2024 11:03:12 +0200 Subject: [PATCH 5/7] Addind Extends --- ARCs/arc-0026.md | 1 + ARCs/{arc-0026-k.md => arc-0078.md} | 9 +++++---- 2 files changed, 6 insertions(+), 4 deletions(-) rename ARCs/{arc-0026-k.md => arc-0078.md} (98%) diff --git a/ARCs/arc-0026.md b/ARCs/arc-0026.md index c1ea3e03d..abf0f5859 100644 --- a/ARCs/arc-0026.md +++ b/ARCs/arc-0026.md @@ -8,6 +8,7 @@ type: Standards Track category: Interface sub-category: General created: 2022-04-21 +extended-by: 78 --- ## Abstract diff --git a/ARCs/arc-0026-k.md b/ARCs/arc-0078.md similarity index 98% rename from ARCs/arc-0026-k.md rename to ARCs/arc-0078.md index bb6a704a9..5b8f3ea28 100644 --- a/ARCs/arc-0026-k.md +++ b/ARCs/arc-0078.md @@ -1,5 +1,5 @@ --- -arc: 26-k +arc: 78 title: URI scheme, keyreg extension description: A specification for encoding Key Registration Transactions in a URI format. author: Tasos Bitsios (@tasosbit) @@ -8,6 +8,7 @@ type: Standards Track category: Interface sub-category: General created: 2024-10-02 +extends: 26 --- ## Abstract @@ -78,7 +79,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-26-K URI encoding. -#### Encoding with minimum fee +#### Encoding with minimum fee The following raw keyreg transaction: @@ -101,7 +102,7 @@ The following raw keyreg transaction: } ``` -Will result in this ARC-26-K encoded URI: +Will result in this ARC-26-K encoded URI: ``` algorand://7IBEAXHK62XEJATU6Q4QYQCDFY475CEKNXGLYQO6QSGCLVMMK4SLVTYLMY? @@ -144,7 +145,7 @@ The following raw keyreg transaction: } ``` -Will result in this ARC-26-K encoded URI: +Will result in this ARC-26-K encoded URI: ``` algorand://7IBEAXHK62XEJATU6Q4QYQCDFY475CEKNXGLYQO6QSGCLVMMK4SLVTYLMY? From febb6a1358415dc0d8c30927a8c94646510342b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane?= Date: Mon, 21 Oct 2024 11:45:58 +0200 Subject: [PATCH 6/7] Update arc-0078.md --- ARCs/arc-0078.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/ARCs/arc-0078.md b/ARCs/arc-0078.md index 5b8f3ea28..1a3d6d505 100644 --- a/ARCs/arc-0078.md +++ b/ARCs/arc-0078.md @@ -3,7 +3,9 @@ arc: 78 title: URI scheme, keyreg extension description: A specification for encoding Key Registration Transactions in a URI format. author: Tasos Bitsios (@tasosbit) -status: Draft +discussions-to: https://github.com/algorandfoundation/ARCs/issues/314 +status: Last Call +last-call-deadline: 2024-10-15 type: Standards Track category: Interface sub-category: General From 34e26612b424db819b903974cadcecafb770b7d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane?= Date: Mon, 21 Oct 2024 11:51:11 +0200 Subject: [PATCH 7/7] Fix typo --- ARCs/arc-0078.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ARCs/arc-0078.md b/ARCs/arc-0078.md index 1a3d6d505..1a9fbd3f2 100644 --- a/ARCs/arc-0078.md +++ b/ARCs/arc-0078.md @@ -32,7 +32,7 @@ algorandurn = "algorand://" algorandaddress [ "?" keyregparams ] algorandaddress = *base32 keyregparams = keyregparam [ "&" keyregparams ] keyregparam = [ typeparam / votekeyparam / selkeyparam / sprfkeyparam / votefstparam / votelstparam / votekdparam / noteparam / feeparam / otherparam ] -typeparam = "type=keyref" +typeparam = "type=keyreg" votekeyparam = "votekey=" *qbase64url selkeyparam = "selkey=" *qbase64url sprfkeyparam = "sprfkey=" *qbase64url @@ -79,7 +79,7 @@ As in the base [ARC-26](./arc-0026.md) standard, the scheme component ("algorand ### Appendix -This section contains encoding examples. The raw transaction object is presented along with the resulting ARC-26-K URI encoding. +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 @@ -104,7 +104,7 @@ The following raw keyreg transaction: } ``` -Will result in this ARC-26-K encoded URI: +Will result in this ARC-78 encoded URI: ``` algorand://7IBEAXHK62XEJATU6Q4QYQCDFY475CEKNXGLYQO6QSGCLVMMK4SLVTYLMY? @@ -121,7 +121,7 @@ Note: newlines added for readability. Note the difference between base64 encoding in the raw object and base64url encoding in the URI parameters. For example, the selection key parameter `selkey` that begins with `+lfw+` in the raw object is encoded in base64url to `-lfw-`. -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-26-K standard does not require this behavior. +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 @@ -147,7 +147,7 @@ The following raw keyreg transaction: } ``` -Will result in this ARC-26-K encoded URI: +Will result in this ARC-78 encoded URI: ``` algorand://7IBEAXHK62XEJATU6Q4QYQCDFY475CEKNXGLYQO6QSGCLVMMK4SLVTYLMY?