From 8904fca95e20d9771247232a7b0f4181717c5295 Mon Sep 17 00:00:00 2001 From: Joe Polny Date: Fri, 28 Jul 2023 10:28:41 -0400 Subject: [PATCH 1/5] Method Reference Discovery --- ARCs/arc-draft_get_refs.md | 60 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 ARCs/arc-draft_get_refs.md diff --git a/ARCs/arc-draft_get_refs.md b/ARCs/arc-draft_get_refs.md new file mode 100644 index 000000000..6c182d35e --- /dev/null +++ b/ARCs/arc-draft_get_refs.md @@ -0,0 +1,60 @@ +--- +arc: +title: Method Reference Discovery +description: A standardized way contracts can reveal which references will be needed to call a specific method +author: Joe Polny (@joe-p) +discussions-to: +status: Draft +type: Standards Track +category: ARC +created: 2023-07-28 +requires (*optional): 4 +--- + +## Abstract +A contract caller needs to know which resources a contract needs to be availible before calling a method. This ARC proposes a standard way to make that information discoverable. + +## Motivation +As of the time of this ARC, it can be hard to know which resources a caller needs to make availible when calling an application. The current solution typically involves proprietary SDKs which can make app usage and composability difficult. + +### Simulation Consideration + +It should be noted that it is currently planned for the algod simulate endpoint to allow readonly execution of a method without providing in references. The response to this endpoint will return the necessary resources. Once this functionality is availible, this ARC will no longer be needed. The primary intent of this ARC is to serve as an intermediate solution. + +## Specification +If an application has a method and the contract wants to make the required resources for calling the method discoverable, it **MUST** implement a readonly method with the same exact signature with an `arcXXXX_` prefix and a return type of `(address[],uint64[],uint64[],(uint64,byte[]))`. + +The return value corresponds to arrays containing the required account, application, asset, and box references respectively. + +The argument values provided to this method when called **SHOULD** match the arguments passed to the method for which the callers wants to know the required resources for. + +The ARCXXXX method **MUST** be readonly. + +## Rationale +The provided method will provide all of the references needed to call the application, which was previously not possible in a standardized way. + +## Backwards Compatibility +N/A + +## Test Cases +N/A + +## Reference Implementation + +### ARC200 example + +In this example, let's say `arc200_totalSupply()uint256` requires two box refences `"baseSupply"` and `"supplyMultiplier"`, each encoded as `byte[]`. + +#### Method Signature + +The ARCXXXX method signature would be `arcXXXX_arc200_totalSupply()(address[],uint64[],uint64[],(uint64,byte[]))` + +#### Return Value + +The ARCXXXX method would return the following value: `[],[],[],[[0, "baseSupply"], [0, "supplyMultiplier"]]` + +## Security Considerations +N/A + +## Copyright +Copyright and related rights waived via CCO. From 28ddcc57cfd361352fc9b88ffdedc7005199ecdd Mon Sep 17 00:00:00 2001 From: Joe Polny Date: Fri, 28 Jul 2023 10:37:46 -0400 Subject: [PATCH 2/5] typo fix --- ARCs/arc-draft_get_refs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ARCs/arc-draft_get_refs.md b/ARCs/arc-draft_get_refs.md index 6c182d35e..6129341f7 100644 --- a/ARCs/arc-draft_get_refs.md +++ b/ARCs/arc-draft_get_refs.md @@ -19,7 +19,7 @@ As of the time of this ARC, it can be hard to know which resources a caller need ### Simulation Consideration -It should be noted that it is currently planned for the algod simulate endpoint to allow readonly execution of a method without providing in references. The response to this endpoint will return the necessary resources. Once this functionality is availible, this ARC will no longer be needed. The primary intent of this ARC is to serve as an intermediate solution. +It should be noted that it is currently planned for the algod simulate endpoint to allow readonly execution of a method without providing references. The response to this endpoint will return the necessary resources. Once this functionality is availible, this ARC will no longer be needed. The primary intent of this ARC is to serve as an intermediate solution. ## Specification If an application has a method and the contract wants to make the required resources for calling the method discoverable, it **MUST** implement a readonly method with the same exact signature with an `arcXXXX_` prefix and a return type of `(address[],uint64[],uint64[],(uint64,byte[]))`. From 34137220bba9edab3f66e76ffff355b94452b2b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane?= Date: Mon, 31 Jul 2023 08:46:58 +0200 Subject: [PATCH 3/5] Update and rename arc-draft_get_refs.md to arc-0051.md --- ARCs/{arc-draft_get_refs.md => arc-0051.md} | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) rename ARCs/{arc-draft_get_refs.md => arc-0051.md} (96%) diff --git a/ARCs/arc-draft_get_refs.md b/ARCs/arc-0051.md similarity index 96% rename from ARCs/arc-draft_get_refs.md rename to ARCs/arc-0051.md index 6129341f7..fe0efe9ad 100644 --- a/ARCs/arc-draft_get_refs.md +++ b/ARCs/arc-0051.md @@ -1,14 +1,14 @@ --- -arc: +arc: 51 title: Method Reference Discovery description: A standardized way contracts can reveal which references will be needed to call a specific method author: Joe Polny (@joe-p) -discussions-to: +discussions-to: https://github.com/algorandfoundation/ARCs/issues/230 status: Draft type: Standards Track category: ARC created: 2023-07-28 -requires (*optional): 4 +requires: 4 --- ## Abstract From 73ef13ef40e1e01d5877ce8b28aebc7b6756f224 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane?= Date: Mon, 31 Jul 2023 09:26:02 +0200 Subject: [PATCH 4/5] Fix linting --- ARCs/arc-0051.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/ARCs/arc-0051.md b/ARCs/arc-0051.md index fe0efe9ad..ff043caaa 100644 --- a/ARCs/arc-0051.md +++ b/ARCs/arc-0051.md @@ -1,7 +1,7 @@ --- arc: 51 title: Method Reference Discovery -description: A standardized way contracts can reveal which references will be needed to call a specific method +description: A way for contracts to reveal which references will be needed to call a specific method author: Joe Polny (@joe-p) discussions-to: https://github.com/algorandfoundation/ARCs/issues/230 status: Draft @@ -9,7 +9,7 @@ type: Standards Track category: ARC created: 2023-07-28 requires: 4 ---- +--- ## Abstract A contract caller needs to know which resources a contract needs to be availible before calling a method. This ARC proposes a standard way to make that information discoverable. @@ -22,13 +22,13 @@ As of the time of this ARC, it can be hard to know which resources a caller need It should be noted that it is currently planned for the algod simulate endpoint to allow readonly execution of a method without providing references. The response to this endpoint will return the necessary resources. Once this functionality is availible, this ARC will no longer be needed. The primary intent of this ARC is to serve as an intermediate solution. ## Specification -If an application has a method and the contract wants to make the required resources for calling the method discoverable, it **MUST** implement a readonly method with the same exact signature with an `arcXXXX_` prefix and a return type of `(address[],uint64[],uint64[],(uint64,byte[]))`. +If an application has a method and the contract wants to make the required resources for calling the method discoverable, it **MUST** implement a readonly method with the same exact signature with an `arc0051_` prefix and a return type of `(address[],uint64[],uint64[],(uint64,byte[]))`. The return value corresponds to arrays containing the required account, application, asset, and box references respectively. The argument values provided to this method when called **SHOULD** match the arguments passed to the method for which the callers wants to know the required resources for. -The ARCXXXX method **MUST** be readonly. +The [ARC-51](./arc-0051.md) method **MUST** be readonly. ## Rationale The provided method will provide all of the references needed to call the application, which was previously not possible in a standardized way. @@ -41,17 +41,17 @@ N/A ## Reference Implementation -### ARC200 example +### [ARC-200](./arc-0200.md) example In this example, let's say `arc200_totalSupply()uint256` requires two box refences `"baseSupply"` and `"supplyMultiplier"`, each encoded as `byte[]`. #### Method Signature -The ARCXXXX method signature would be `arcXXXX_arc200_totalSupply()(address[],uint64[],uint64[],(uint64,byte[]))` +The ARC-51 method signature would be `arc0051_arc200_totalSupply()(address[],uint64[],uint64[],(uint64,byte[]))` #### Return Value -The ARCXXXX method would return the following value: `[],[],[],[[0, "baseSupply"], [0, "supplyMultiplier"]]` +The ARC-51 method would return the following value: `[],[],[],[[0, "baseSupply"], [0, "supplyMultiplier"]]` ## Security Considerations N/A From eb6558712c0f4ea9672487222d9ec574411a9344 Mon Sep 17 00:00:00 2001 From: Joe Polny Date: Mon, 7 Aug 2023 16:32:42 -0400 Subject: [PATCH 5/5] event-based spec --- ARCs/arc-0051.md | 35 ++++++++++++++++------------------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/ARCs/arc-0051.md b/ARCs/arc-0051.md index ff043caaa..82f997e02 100644 --- a/ARCs/arc-0051.md +++ b/ARCs/arc-0051.md @@ -17,21 +17,28 @@ A contract caller needs to know which resources a contract needs to be availible ## Motivation As of the time of this ARC, it can be hard to know which resources a caller needs to make availible when calling an application. The current solution typically involves proprietary SDKs which can make app usage and composability difficult. -### Simulation Consideration - -It should be noted that it is currently planned for the algod simulate endpoint to allow readonly execution of a method without providing references. The response to this endpoint will return the necessary resources. Once this functionality is availible, this ARC will no longer be needed. The primary intent of this ARC is to serve as an intermediate solution. - ## Specification -If an application has a method and the contract wants to make the required resources for calling the method discoverable, it **MUST** implement a readonly method with the same exact signature with an `arc0051_` prefix and a return type of `(address[],uint64[],uint64[],(uint64,byte[]))`. +If an application has a method and the contract wants to make the required resources for calling the method discoverable, it **MUST** implement a readonly method with the same exact signature with an `requirements_` prefix and return type of `void`. -The return value corresponds to arrays containing the required account, application, asset, and box references respectively. +The app **MAY** emit one or more of the following events in accordance with [ARC-28](./arc-0028.md). No events emitted **SHOULD** indicate that there are no external requirements for a successful method call. + +| Event Signature | Description | +| --------------- | ----------- | +| `requirement_box(uint64, byte[],uint16,bool)` | `uint64` to signify the boxes application, `byte[]` to signify the box key, `uint16` to signify the box size (in bytes), and `bool` to signify whether the box is being written to (false signifies readonly) | +| `requirement_account(address)` | An account that needs to be made available | +| `requirement_application(uint64)` | An application that needs to be made available | +| `requirement_asset(uint64)` | An asset that needs to be made available | +| `requirement_account_x_asset(address,uint64)` | An account and asset pairing needed to do an asset balance lookup | +| `requirement_account_x_application(address,uint64)` | An account and application pairing needed to read local state | +| `requirement_fee(uint64)` | Inner transaction fees the sender must cover. All of these events emitted **MUST** be added together | +| `requirement_txn_field(uint8,string,byte[])` | `uint8` signifying the index of the transaction this field corresponds to, `string` signifying the name of the transaction field, and `btye[]` signifying the expected value of the transaction field The argument values provided to this method when called **SHOULD** match the arguments passed to the method for which the callers wants to know the required resources for. -The [ARC-51](./arc-0051.md) method **MUST** be readonly. +This method **MUST** be readonly. ## Rationale -The provided method will provide all of the references needed to call the application, which was previously not possible in a standardized way. +The `requirements_` method will provide all of the information needed to successfully call the application, which was previously not possible in a standardized way. ## Backwards Compatibility N/A @@ -41,17 +48,7 @@ N/A ## Reference Implementation -### [ARC-200](./arc-0200.md) example - -In this example, let's say `arc200_totalSupply()uint256` requires two box refences `"baseSupply"` and `"supplyMultiplier"`, each encoded as `byte[]`. - -#### Method Signature - -The ARC-51 method signature would be `arc0051_arc200_totalSupply()(address[],uint64[],uint64[],(uint64,byte[]))` - -#### Return Value - -The ARC-51 method would return the following value: `[],[],[],[[0, "baseSupply"], [0, "supplyMultiplier"]]` +TODO ## Security Considerations N/A