Skip to content

Latest commit

 

History

History
84 lines (50 loc) · 4.96 KB

0016.md

File metadata and controls

84 lines (50 loc) · 4.96 KB
Raw

CIP [0016]: Universal celo protocol URI scheme for QRs/deep links

  • Date: 2020-07-27
  • Author: @yorhodes
  • Status: WIP

Overview

Create a standard URI scheme for encoding interacting with the Celo protocol for various consumers including SDKs, mobile/web wallets, and end users. Facilitate development of QR systems by standardizing usage and unifying scheme for interoperability.

Goals

  • establish URI standard compatible with mobile app intents that optimizes for memory and performance
  • enable simple construction of URIs by humans without deep Celo protocol understanding
  • enable simple construction of QRs by code from arbitrary Celo transactions

Proposed Solution

Syntax

Celo protocol URLs contain "celo" in their schema (protocol) part and are constructed as follows:

request                 = "celo://" target [ "/" endpoint ] [ "?" parameters ]

target                  = E164_PHONE_NUMBER / registry_id / celo_address
registry_id             = "StableToken" / "GoldToken" / "LockedGold" / ...
celo_address            = ( "0x" 40*HEXDIG )

endpoint                = function_name "(" [ function_args ] ")
function_name           = "cUSD" / "CELO" / STRING
function_args           = function_arg *( "," function_arg )
function_arg            = value [ ":" TYPE ]

parameters              = parameter *( "&" parameter )
parameter               = key "=" value
key                     = "value" / "gas" / "gasPrice" / "feeCurrency" / "gatewayFee" / "gatewayFeeRecipient" / "localValue" / "localCurrencyCode" / "from" / "nonce"
value                   = NUMBER / STRING / celo_address

Semantics

TYPE is a standard ABI type name, as defined in Ethereum Contract ABI specification. STRING is a URL-encoded unicode string of arbitrary length, where delimiters and the percentage symbol (%) are mandatorily hex-encoded with a % prefix.

E164_PHONE_NUMBER is a standard E164 universal phone number, as defined by the International Telecommunication Union E164 Number Specification.

registry_id is provided to simplify and shorten Celo protocol-aware contract interactions (to be eventually translated by the application to a registry-specified 40 byte address). The canonical list of registry identifiers can be obtained from the contract deployed at 0x000000000000000000000000000000000000ce10.

cUSD and CELO are provided as a concise encoding of native ERC20 transfers that would otherwise be represented via a contract registry_id, function_name, and recipient celo_address. These optionally take 1 function_arg which is an amount in the token denomination.

function_args have an optional TYPE because, in some cases, the application may have knowledge of the ABIs deeming the solidity types unnecessary. These can most likely be omitted when used with a Celo registry contract via a registry_id target.

localValue is intended for use with localCurrencyCode and specifies a value in a locale-specific denomination (to be eventually translated by the application to a Celo-specific denomination). Resolving value with localValue is discretionary.

All key values should be acommodated in abbreviations as the first character from each camelcase section. As an example, value, localCurrency and gatewayFeeRecipient could be provided as v, lc and gfr.

Rationale

Various QR schemes are used across implementations such as Valora, ContractKit, and likely others.

Expanding the target spec to be inclusive of phone numbers and contract registry identifiers makes statically generated QR codes less likely to expire than if an address (which can be changed or compromised) is used.

For low-end mobile devices, QR codes are primarily bottlenecked by pixel density and image quality (Reed-Solomon error-correction). This proposal optimizes for these parameters and enables short URIs which can be deep-linked to application functionality.

  • Valora example: celo://+442071838750/cUSD(10) (29 chars)

Alternative Solutions

A more ethereum-like VM generalized approach would reduce spec complexity but fails to meet aforementioned goals.

Risks

  • Ease of use for phone number targets and/or unique mapping of phone number to address.

Useful Links

Adapted from ERC 67, EIP 681, and EIP 831 to Celo protocol needs and users

More info on QR pixel density and Reed-Solomon error correction.

Implementation

  • To follow.
  • Or a link to a PR.

Add any implementation considerations here. For all proposals going through the governance process, this section should reference the code implementing the proposed change. It’s recommended to get community feedback before writing any code.