From cfd01a695ddfc8581ab76c42e05e0e81d58010de Mon Sep 17 00:00:00 2001 From: MG Date: Mon, 21 Oct 2024 17:44:08 +0300 Subject: [PATCH 01/11] ARC-79, extends ARC-26 URI scheme with App NoOp calls This ARC proposal extends base ARC-26 URI scheme with missing params required for Algorand application NoOp calls. --- ARCs/arc-0079 | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 ARCs/arc-0079 diff --git a/ARCs/arc-0079 b/ARCs/arc-0079 new file mode 100644 index 000000000..9074ceeea --- /dev/null +++ b/ARCs/arc-0079 @@ -0,0 +1,112 @@ +--- +arc: 79 +title: URI scheme, App NoOp call extension +description: A specification for encoding NoOp Application call Transactions in a URI format. +author: MG (@emg110) +discussions-to: +status: Last Call +last-call-deadline: 2024-10-30 +type: Standards Track +category: Interface +sub-category: General +created: 2024-09-11 +extends: 26 +--- + +## Abstract +NoOp calls are Generic application calls to execute the Algorand smart contract ApprovalPrograms. + +This URI specification represents an extension to the base Algorand URI encoding standard ([ARC-26](./arc-0026.md)) that specifies encoding of application NoOp transactions into RFC 3986 standard URIs. + +## Specification + +### General format + +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 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 (args, refs, etc.) must be encoded with base64url as specified in RFC 4648 section 5. + +### ABNF Grammar + +``` +algorandurn = "algorand://" algorandaddress [ "?" noopparams ] +algorandaddress = *base32 +noopparams = noopparam [ "&" noopparams ] +noopparam = [ typeparam / appparam / methodparam / argparam / boxparam / assetarrayparam / accountarrayparam / apparrayparam / feeparam / otherparam ] +typeparam = "type=appl" +appparam = "app=" *digit +methodparam = "method=" *qchar +boxparam = "box=" *qbase64url +argparam = "arg=" (*qchar | *digit) +feeparam = "fee=" *digit +accountparam = "account=" *qchar +assetparam = "asset=" *digit +noteparam = (xnote | note) +xnote = "xnote=" *qchar +note = "note=" *qchar +otherparam = qchar *qchar [ "=" *qchar ] +``` + +- "qchar" corresponds to valid characters of an RFC 3986 URI query component, excluding the "=" and "&" characters, which this specification takes as separators. +- "qbase64url" corresponds to valid characters of "base64url" encoding, as defined in RFC 4648 section 5 +- All params from the base [ARC-26](./arc-0026.md) standard, are supported and usable if fit the NoOp application call context (e.g. note) +- 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 "appl". Used to disambiguate the transaction type from the base [ARC-26](./arc-0026.md) standard and other possible extensions + +- app: The first reference is sed to specify the called application (Algorand Smart Contract) ID and is mandatory. extra references are optional and will be used in the Application NoOp call's foreign applications array. + +- method: Specify the full method expression (e.g "example_method(uint64,uint64)void"). + +- arg: specify args used for calling NoOp method, to be encoded within URI. + +- box: Box references to be used in Application NoOp method call box array. + +- asset: Asset reference to be used in Application NoOp method call foreign assets array. + +- account: Account or nfd address to be used in Application NoOp method call foreign accounts array. + +- 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](./arc-0026.md). A URL-encoded default notes field value that the the user interface may optionally make editable by the user. + +- fee: Optional. An optional static fee to set for the transaction in microAlgos. + +- (others): optional, for future extensions + +### Template URI vs actionable URI + +If the URI is constructed for templating only so that other dApps, wallets or protocols could use it by templating the Algorand account, then the account address in URI must be ZeroAddress ("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ"). Since ZeroAddress cannot initiate any action this approach is considered non-vulnerable and secure. + +### Example + +Call claim(uint64,uint64)byte[] method on contract 11111111 paying a fee of 10000 micro ALGO from an specific address + +``` +algorand://TMTAD6N22HCS2LKH7677L2KFLT3PAQWY6M4JFQFXQS32ECBFC23F57RYX4?app=11111111&method=claim(uint64,uint64)byte[]&arg=20000&arg=474567&asset=45&fee=10000 +``` + +Call the same claim(uint64,uint64)byte[] method on contract 11111111 paying a default 1000 micro algo fee + +``` +algorand://TMTAD6N22HCS2LKH7677L2KFLT3PAQWY6M4JFQFXQS32ECBFC23F57RYX4?app=11111111&method=claim(uint64,uint64)byte[]&arg=20000&arg=474567&asset=45&app=22222222&app=33333333 +``` + +Note: Here in the second example, the fee is omitted from the URI (due to being set to the minimum 1,000 microAlgos), also two app references have been added to foreign applications array of transaction. + + +## Rationale + +Algorand application NoOp method calls cover the majority of application transactions on Algorand and have a wide range of use-cases. For offline or not directly connected implementations of such calls in certain conditions where the runtime knows exactly what application needs to be called and using which arguments and arrays, the base ARC26 standard needed to be extended to support. This ARC provides that extension for ARC-26. + +## Security Considerations + +None. + +## Copyright + +Copyright and related rights waived via CCO. From 044cc8a6159dee3e945d2b2fab332b0ac707f307 Mon Sep 17 00:00:00 2001 From: MG Date: Mon, 21 Oct 2024 17:45:43 +0300 Subject: [PATCH 02/11] Update ARC-26 to be extended by ARC-79 ARC-79 extends ARC-26 with application NoOp call params. --- ARCs/arc-0026.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ARCs/arc-0026.md b/ARCs/arc-0026.md index abf0f5859..19bd2a3db 100644 --- a/ARCs/arc-0026.md +++ b/ARCs/arc-0026.md @@ -8,7 +8,7 @@ type: Standards Track category: Interface sub-category: General created: 2022-04-21 -extended-by: 78 +extended-by: 78, 79 --- ## Abstract From fc6d84fd99ce33671c657186a7b11ce841b2a8b0 Mon Sep 17 00:00:00 2001 From: MG Date: Mon, 21 Oct 2024 18:33:07 +0300 Subject: [PATCH 03/11] Update ARCs/arc-0079 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Stéphane --- ARCs/arc-0079 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ARCs/arc-0079 b/ARCs/arc-0079 index 9074ceeea..1e1db9890 100644 --- a/ARCs/arc-0079 +++ b/ARCs/arc-0079 @@ -3,7 +3,7 @@ arc: 79 title: URI scheme, App NoOp call extension description: A specification for encoding NoOp Application call Transactions in a URI format. author: MG (@emg110) -discussions-to: +discussions-to: https://github.com/algorandfoundation/ARCs/issues/319 status: Last Call last-call-deadline: 2024-10-30 type: Standards Track From bfd4f8d641180ce2be331f7395de91470e134979 Mon Sep 17 00:00:00 2001 From: MG Date: Mon, 21 Oct 2024 18:33:19 +0300 Subject: [PATCH 04/11] Update ARCs/arc-0079 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Stéphane --- ARCs/arc-0079 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ARCs/arc-0079 b/ARCs/arc-0079 index 1e1db9890..e8c3722c6 100644 --- a/ARCs/arc-0079 +++ b/ARCs/arc-0079 @@ -101,7 +101,7 @@ Note: Here in the second example, the fee is omitted from the URI (due to being ## Rationale -Algorand application NoOp method calls cover the majority of application transactions on Algorand and have a wide range of use-cases. For offline or not directly connected implementations of such calls in certain conditions where the runtime knows exactly what application needs to be called and using which arguments and arrays, the base ARC26 standard needed to be extended to support. This ARC provides that extension for ARC-26. +Algorand application NoOp method calls cover the majority of application transactions on Algorand and have a wide range of use-cases. For offline or not directly connected implementations of such calls in certain conditions where the runtime knows exactly what application needs to be called and using which arguments and arrays, the base ARC-26 standard needed to be extended to support. This ARC provides that extension for ARC-26. ## Security Considerations From 1250f5ba2e3de4121fed9865e1520df1327ce137 Mon Sep 17 00:00:00 2001 From: MG Date: Mon, 21 Oct 2024 18:36:34 +0300 Subject: [PATCH 05/11] Update ARC-79 file name --- ARCs/{arc-0079 => arc-0079.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename ARCs/{arc-0079 => arc-0079.md} (100%) diff --git a/ARCs/arc-0079 b/ARCs/arc-0079.md similarity index 100% rename from ARCs/arc-0079 rename to ARCs/arc-0079.md From 600edbaadc5485baf02d895afa177a2e53dffa84 Mon Sep 17 00:00:00 2001 From: MG Date: Mon, 21 Oct 2024 18:38:57 +0300 Subject: [PATCH 06/11] Removed ARC-26 duplicates --- ARCs/arc-0079.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/ARCs/arc-0079.md b/ARCs/arc-0079.md index e8c3722c6..880f72092 100644 --- a/ARCs/arc-0079.md +++ b/ARCs/arc-0079.md @@ -41,9 +41,6 @@ argparam = "arg=" (*qchar | *digit) feeparam = "fee=" *digit accountparam = "account=" *qchar assetparam = "asset=" *digit -noteparam = (xnote | note) -xnote = "xnote=" *qchar -note = "note=" *qchar otherparam = qchar *qchar [ "=" *qchar ] ``` @@ -70,10 +67,6 @@ otherparam = qchar *qchar [ "=" *qchar ] - account: Account or nfd address to be used in Application NoOp method call foreign accounts array. -- 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](./arc-0026.md). A URL-encoded default notes field value that the the user interface may optionally make editable by the user. - - fee: Optional. An optional static fee to set for the transaction in microAlgos. - (others): optional, for future extensions From c17f32ba3aa07180bd6535ea14d1b93161b722fb Mon Sep 17 00:00:00 2001 From: MG Date: Fri, 15 Nov 2024 15:47:12 +0300 Subject: [PATCH 07/11] Updated examples and added type --- ARCs/arc-0079.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/ARCs/arc-0079.md b/ARCs/arc-0079.md index 880f72092..50cfac5a1 100644 --- a/ARCs/arc-0079.md +++ b/ARCs/arc-0079.md @@ -73,28 +73,29 @@ otherparam = qchar *qchar [ "=" *qchar ] ### Template URI vs actionable URI -If the URI is constructed for templating only so that other dApps, wallets or protocols could use it by templating the Algorand account, then the account address in URI must be ZeroAddress ("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ"). Since ZeroAddress cannot initiate any action this approach is considered non-vulnerable and secure. +If the URI is constructed so that other dApps, wallets or protocols could use it with their runtime accounts of interest, then the account address in URI must be ZeroAddress ("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ"). Since ZeroAddress cannot initiate any action this approach is considered non-vulnerable and secure. ### Example Call claim(uint64,uint64)byte[] method on contract 11111111 paying a fee of 10000 micro ALGO from an specific address ``` -algorand://TMTAD6N22HCS2LKH7677L2KFLT3PAQWY6M4JFQFXQS32ECBFC23F57RYX4?app=11111111&method=claim(uint64,uint64)byte[]&arg=20000&arg=474567&asset=45&fee=10000 +algorand://TMTAD6N22HCS2LKH7677L2KFLT3PAQWY6M4JFQFXQS32ECBFC23F57RYX4?type=appl&app=11111111&method=claim(uint64,uint64)byte[]&arg=20000&arg=474567&asset=45&fee=10000 ``` Call the same claim(uint64,uint64)byte[] method on contract 11111111 paying a default 1000 micro algo fee ``` -algorand://TMTAD6N22HCS2LKH7677L2KFLT3PAQWY6M4JFQFXQS32ECBFC23F57RYX4?app=11111111&method=claim(uint64,uint64)byte[]&arg=20000&arg=474567&asset=45&app=22222222&app=33333333 +algorand://TMTAD6N22HCS2LKH7677L2KFLT3PAQWY6M4JFQFXQS32ECBFC23F57RYX4?type=appl&app=11111111&method=claim(uint64,uint64)byte[]&arg=20000&arg=474567&asset=45&app=22222222&app=33333333 ``` -Note: Here in the second example, the fee is omitted from the URI (due to being set to the minimum 1,000 microAlgos), also two app references have been added to foreign applications array of transaction. +Note: If the fee is omitted , it means that Minimum Fee is preferred to be used for transaction. ## Rationale -Algorand application NoOp method calls cover the majority of application transactions on Algorand and have a wide range of use-cases. For offline or not directly connected implementations of such calls in certain conditions where the runtime knows exactly what application needs to be called and using which arguments and arrays, the base ARC-26 standard needed to be extended to support. This ARC provides that extension for ARC-26. +Algorand application NoOp method calls cover the majority of application transactions in Algorand and have a wide range of use-cases. +For use-cases where the runtime knows exactly what the called application needs in terms of arguments and transaction arrays and there are no direct interactions, this extension will be required since ARC-26 standard does not currently support application calls. ## Security Considerations From 1f10d997a750fe95ca58d2a4c4b7eb6b18c12d0f Mon Sep 17 00:00:00 2001 From: MG Date: Fri, 15 Nov 2024 15:49:34 +0300 Subject: [PATCH 08/11] Add Recurring types description --- ARCs/arc-0079.md | 1 + 1 file changed, 1 insertion(+) diff --git a/ARCs/arc-0079.md b/ARCs/arc-0079.md index 50cfac5a1..95fe08be3 100644 --- a/ARCs/arc-0079.md +++ b/ARCs/arc-0079.md @@ -90,6 +90,7 @@ algorand://TMTAD6N22HCS2LKH7677L2KFLT3PAQWY6M4JFQFXQS32ECBFC23F57RYX4?type=appl& ``` Note: If the fee is omitted , it means that Minimum Fee is preferred to be used for transaction. +Note 2: Recurring apps, assets and accounts, add those into transaction arrays (foreign apps, foreign assets, foreign accounts and boxes). ## Rationale From 27eb2cafdff658360ca56960c13d193216ba5fd1 Mon Sep 17 00:00:00 2001 From: MG Date: Fri, 15 Nov 2024 16:48:58 +0300 Subject: [PATCH 09/11] Updated content --- ARCs/arc-0079.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/ARCs/arc-0079.md b/ARCs/arc-0079.md index 95fe08be3..bf5018466 100644 --- a/ARCs/arc-0079.md +++ b/ARCs/arc-0079.md @@ -16,7 +16,7 @@ extends: 26 ## Abstract NoOp calls are Generic application calls to execute the Algorand smart contract ApprovalPrograms. -This URI specification represents an extension to the base Algorand URI encoding standard ([ARC-26](./arc-0026.md)) that specifies encoding of application NoOp transactions into RFC 3986 standard URIs. +This URI specification proposes an extension to the base Algorand URI encoding standard ([ARC-26](./arc-0026.md)) that specifies encoding of application NoOp transactions into RFC 3986 standard URIs. ## Specification @@ -24,7 +24,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 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 (args, refs, etc.) must be encoded with base64url as specified in RFC 4648 section 5. +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 (args, refs, etc.) **MUST** be encoded with base64url as specified in RFC 4648 section 5. ### ABNF Grammar @@ -47,7 +47,7 @@ otherparam = qchar *qchar [ "=" *qchar ] - "qchar" corresponds to valid characters of an RFC 3986 URI query component, excluding the "=" and "&" characters, which this specification takes as separators. - "qbase64url" corresponds to valid characters of "base64url" encoding, as defined in RFC 4648 section 5 - All params from the base [ARC-26](./arc-0026.md) standard, are supported and usable if fit the NoOp application call context (e.g. note) -- 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. +- 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 @@ -55,7 +55,7 @@ otherparam = qchar *qchar [ "=" *qchar ] - type: fixed to "appl". Used to disambiguate the transaction type from the base [ARC-26](./arc-0026.md) standard and other possible extensions -- app: The first reference is sed to specify the called application (Algorand Smart Contract) ID and is mandatory. extra references are optional and will be used in the Application NoOp call's foreign applications array. +- app: The first reference is set to specify the called application (Algorand Smart Contract) ID and is mandatory. Additional references are optional and will be used in the Application NoOp call's foreign applications array. - method: Specify the full method expression (e.g "example_method(uint64,uint64)void"). @@ -71,10 +71,19 @@ otherparam = qchar *qchar [ "=" *qchar ] - (others): optional, for future extensions +Note 1: If the fee is omitted , it means that Minimum Fee is preferred to be used for transaction. + +Note 2: Recurring apps, assets and accounts, add those into transaction arrays (foreign apps, foreign assets, foreign accounts and boxes). + ### Template URI vs actionable URI -If the URI is constructed so that other dApps, wallets or protocols could use it with their runtime accounts of interest, then the account address in URI must be ZeroAddress ("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ"). Since ZeroAddress cannot initiate any action this approach is considered non-vulnerable and secure. +If the URI is constructed so that other dApps, wallets or protocols could use it with their runtime Algorand entities of interest, then : +- The placeholder account/app address in URI **MUST** be ZeroAddress ("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ"). Since ZeroAddress cannot initiate any action this approach is considered non-vulnerable and secure. +- The placeholder app ID **MUST** 0. e.g. `&app=11111111&app=0` +- The placeholder asset ID **MUST** be 0. e.g. `&asset=11111111&asset=0` +- The placeholder box reference **MUST** be 0. e.g. `&box=nodes&box=0` + ### Example Call claim(uint64,uint64)byte[] method on contract 11111111 paying a fee of 10000 micro ALGO from an specific address @@ -89,8 +98,6 @@ Call the same claim(uint64,uint64)byte[] method on contract 11111111 paying a de algorand://TMTAD6N22HCS2LKH7677L2KFLT3PAQWY6M4JFQFXQS32ECBFC23F57RYX4?type=appl&app=11111111&method=claim(uint64,uint64)byte[]&arg=20000&arg=474567&asset=45&app=22222222&app=33333333 ``` -Note: If the fee is omitted , it means that Minimum Fee is preferred to be used for transaction. -Note 2: Recurring apps, assets and accounts, add those into transaction arrays (foreign apps, foreign assets, foreign accounts and boxes). ## Rationale From 510a827c5a4779940433317de22f212c1f94a28b Mon Sep 17 00:00:00 2001 From: MG Date: Fri, 15 Nov 2024 16:56:14 +0300 Subject: [PATCH 10/11] Update content --- ARCs/arc-0079.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/ARCs/arc-0079.md b/ARCs/arc-0079.md index bf5018466..aaad03e72 100644 --- a/ARCs/arc-0079.md +++ b/ARCs/arc-0079.md @@ -73,16 +73,12 @@ otherparam = qchar *qchar [ "=" *qchar ] Note 1: If the fee is omitted , it means that Minimum Fee is preferred to be used for transaction. -Note 2: Recurring apps, assets and accounts, add those into transaction arrays (foreign apps, foreign assets, foreign accounts and boxes). - ### Template URI vs actionable URI If the URI is constructed so that other dApps, wallets or protocols could use it with their runtime Algorand entities of interest, then : - The placeholder account/app address in URI **MUST** be ZeroAddress ("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ"). Since ZeroAddress cannot initiate any action this approach is considered non-vulnerable and secure. -- The placeholder app ID **MUST** 0. e.g. `&app=11111111&app=0` -- The placeholder asset ID **MUST** be 0. e.g. `&asset=11111111&asset=0` -- The placeholder box reference **MUST** be 0. e.g. `&box=nodes&box=0` + ### Example From e090bf7905dde1e71cd1aa5abc91831d5cadb0aa Mon Sep 17 00:00:00 2001 From: MG Date: Fri, 15 Nov 2024 17:15:54 +0300 Subject: [PATCH 11/11] Update account to base32 --- ARCs/arc-0079.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ARCs/arc-0079.md b/ARCs/arc-0079.md index aaad03e72..f6afbbad2 100644 --- a/ARCs/arc-0079.md +++ b/ARCs/arc-0079.md @@ -39,7 +39,7 @@ methodparam = "method=" *qchar boxparam = "box=" *qbase64url argparam = "arg=" (*qchar | *digit) feeparam = "fee=" *digit -accountparam = "account=" *qchar +accountparam = "account=" *base32 assetparam = "asset=" *digit otherparam = qchar *qchar [ "=" *qchar ] ```