Algorand MCP

--- arc: 47 title: Logic Signature Templates description: Defining templated logic signatures so wallets can safely sign them. author: Joe Polny (@joe-p) discussions-to: https://github.com/algorandfoundation/ARCs/issues/226 status: Final type: Standards Track category: ARC sub-category: Wallet created: 2023-07-17 --- ## Abstract This standard allows wallets to sign known logic signatures and clearly tell the user what they are signing. ## Motivation Currently, most Algorand wallets do not enable the signing of logic signature programs for the purpose of delegation. The rationale is to prevent users from signing malicious programs, but this limitation also prevents non-malicious delegated logic signatures from being used in the Algorand ecosystem. As such, there needs to be a way to provide a safe way for wallets to sign logic signatures without putting users at risk. ## Specification A logic signature **MUST** be described via the following JSON interface(s): ### Interface ```typescript interface LogicSignatureDescription { name: string, description: string, program: string, variables: { variable: string, name: string, type: string, description: string }[] } ``` | Key | Description | | --- | ----------- | | `name` | The name of the logic signature. **SHOULD** be short and descriptive | | `description` | A description of what the logic signature does | | `program` | base64 encoding of the TEAL program source | `variables` | An array of variables in the program | | `variables.variable` | The name of the variable in the templated program. | | `variables.name` | Human-friendly name for the variable. **SHOULD** be short and descriptive | | `variables.type` | **MUST** be a type defined below in the `type` section | | `variables.description` | A description of how this variable is used in the program | ### Variables A variable in the program **MUST** be start with `TMPL_` #### Types All non-reference ABI types **MUST** be supported by the client. ABI values **MUST** be encoded in base16 (with the leading `0x`) with the following exceptions: | Type | Description | | ---- | ----------- | | `address` | 58-character base32 Algorand public address. Typically to be used as an argument to the `addr` opcode. Front-ends **SHOULD** provide a link to the address on an explorer | `application` | Application ID. Alias for `uint64`. Front-ends **SHOULD** provide a link to the app on an explorer | | `asset` | Asset ID. Alias for `uint64`. Front-ends **SHOULD** provide a link to the asset on an explorer | | `string` | UTF-8 string. Typically used as an argument to `byte`, `method`, or a branching opcode. | `hex` | base16 encoding of binary data. Typically used as an argument to `byte`. **MUST** be prefixed with `0x` | For all other value, front-ends **MUST** decode the ABI value to display the human-readable value to the user. ### Input Validation All ABI values **MUST** be encoded as base16 and prefixed with `0x`, with the exception of `uint64` which should be provided as an integer. String values **MUST NOT** include any unescaped `"` to ensure there is no TEAL injection. All values **MUST** be validated to ensure they are encoded properly. This includes the following checks: * An `address` value must be a valid Algorand address * A `uint64`, `application`, or `asset` value must be a valid unsigned 64-bit integer ### Unique Identification To enable unique identification of a description, clients **MUST** calculate the SHA256 hash of the JSON description canonicalized in accordance with <a href="https://www.rfc-editor.org/rfc/rfc8785">RFC 8785</a>. ### WalletConnect Method For wallets to support this ARC, they need to support the a `algo_templatedLsig` method. The method expects three parameters described by the interface below ```ts interface TemplatedLsigParams { /** The canoncalized ARC47 templated lsig JSON as described in this ARC */ arc47: string /** The values of the templated variables, if there are any */ values?: {[variable: string]: string | number} /** The hash of the expected program. Wallets should compile the lsig with the given values to verify the program hash matches */ hash: string } ``` ## Rationale This provides a way for frontends to clearly display to the user what is being signed when signing a logic signature. Template variables must be immediate arguments. Otherwise a string variable could specify the opcode in the program, which could have unintended and unclear consequences. `TMPL_` prefix is used to align with existing template variable tooling. Hashing canonicalized JSON is useful for ensuring clients, such as wallets, can create a allowlist of templated logic signatures. ## Backwards Compatibility N/A ## Test Cases N/A ## Reference Implementation A reference implementation can be found in the`../assets/arc-0047` folder. [lsig.teal](../assets/arc-0047/lsig.teal) contains the templated TEAL code for a logic signature that allows payments of a specific amount every 25,000 blocks. [dapp.ts](../assets/arc-0047/dapp.ts) contains a TypeScript script showcasing how a dapp would form a wallet connect request for a templated logic signature. [wallet.ts](../assets/arc-0047/wallet.ts) contains a TypeScript script showcasing how a wallet would handle a request for signing a templated logic signature. [validate.ts](../assets/arc-0047/validate.ts) contains a TypeScript script showcasing how one could validate templated TEAL and variable values. ### String Variables #### Invalid: Partial Argument ``` #pragma version 9 byte "Hello, TMPL_NAME" ``` This is not valid because `TMPL_NAME` is not the full immediate argument. #### Invalid: Not An Argument ``` #pragma version 9 TMPL_PUSH_HELLO_NAME ``` This is not valid because `TMPL_PUSH_HELLO_NAME` is not an immediate argument to an opcode. #### Valid ``` #pragma version 9 byte TMPL_HELLO_NAME ``` This is valid as `TMPL_HELLO_NAME` is the entire immediate argument of the `byte` opcode. A possible value could be `Hello, AlgoDev` ### Hex Variables #### Valid ``` #pragma version 9 byte TMPL_DEAD_BEEF ``` This is valid as `TMPL_DEAD_BEEF` is the full immediate argument to the `byte` opcode. A possible value could be `0xdeadbeef`. ## Security Considerations It should be made clear that this standard alone does not define how frontends, particularly wallets, should deem a logic signature to be safe. This is a decision made solely by the front-ends as to which logic signatures they allow to be signed. It is **RECOMMENDED** to only support the signing of audited or otherwise trusted logic signatures. ## Copyright Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CCO</a>.