ARC-51: Method Reference Discovery

ARCs/arc-0051.md

@@ -0,0 +1,57 @@
+---
+arc: 51
+title: Method Reference Discovery
+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
+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.
+
+## 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.
+
+## 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 `requirements_` prefix and return type of `void`. 
+
+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.
+
+This method **MUST** be readonly.
+
+## Rationale
+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
+
+## Test Cases
+N/A
+
+## Reference Implementation
+
+TODO
+
+## Security Considerations
+N/A
+
+## Copyright
+Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CCO</a>.