ARC0047: Logic Signature Templates

ARCs/arc-0047.md

@@ -0,0 +1,170 @@
+---
+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
+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 supprt 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>.

assets/arc-0047/.gitignore

@@ -0,0 +1,169 @@
+# Based on https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
+
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+\*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+\*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+\*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+\*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# dotenv environment variable files
+
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.cache
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+
+# Nuxt.js build / generate output
+
+.nuxt
+dist
+
+# Gatsby files
+
+.cache/
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+.cache
+
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.\*

assets/arc-0047/dapp.ts

@@ -0,0 +1,49 @@
+import algosdk from 'algosdk'
+import { readFileSync } from 'fs'
+import {canonicalize} from 'json-canonicalize'
+import { formatJsonRpcRequest } from "@json-rpc-tools/utils";
+import { sha256 } from 'js-sha256';
+
+const algodClient = new algosdk.Algodv2('a'.repeat(64), 'http://localhost', 4001)
+
+const teal = readFileSync('./lsig.teal').toString()
+
+const arc47 = {
+    name: "25000 block payment",
+    description: "Allows a payment to be made every 25000 blocks of a specific amount to a specific address",
+    program: btoa(teal),
+    variables: [
+        {
+            name: "Payment Amount",
+            variable: "TMPL_AMOUNT",
+            type: "uint64",
+            description: "Amount of the payment transaction in microAlgos"
+        },
+        {
+            name: "Payment Receiver",
+            variable: "TMPL_RECEIVER",
+            type: "address",
+            description: "Address to which the payment transaction is sent"
+        }
+    ],
+}
+
+const values: Record<string, string | number> = {
+    TMPL_AMOUNT: 1000000,
+    TMPL_RECEIVER: 'Y76M3MSY6DKBRHBL7C3NNDXGS5IIMQVQVUAB6MP4XEMMGVF2QWNPL226CA'
+}
+
+let finalTeal = teal
+
+for (const variable in values) {
+    finalTeal = finalTeal.replaceAll(variable, values[variable].toString())
+}
+
+const result = await algodClient.compile(finalTeal).do()
+
+const requestParams = [canonicalize(arc47), JSON.stringify(values), result.hash]
+
+const walletConnectRequest = formatJsonRpcRequest('algo_signTemplatedLsig', requestParams);
+
+console.log(`Request Params: ${console.log(requestParams)}`)
+console.log(`ARC47 SHA256: ${sha256(canonicalize(arc47))}`)