Logic Signature Templates

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

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 RFC 8785.

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

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 thehttps://raw.githubusercontent.com/algorandfoundation/ARCs/main/assets/arc-0047 folder.

lsig.teal contains the templated TEAL code for a logic signature that allows payments of a specific amount every 25,000 blocks.

dapp.ts contains a TypeScript script showcasing how a dapp would form a wallet connect request for a templated logic signature.

wallet.ts contains a TypeScript script showcasing how a wallet would handle a request for signing a templated logic signature.

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 CCO.