CIP 13 - Cardano URI Scheme
- ABNF Grammar (Proposal)
- Security Considerations
- Why not use Universal links, deep links and other non-protocol-based Solution
- Read More
This proposal describes a basic URI scheme to handle Ada transfers and links to stake pools.
For payment URIs:
Users who create community content often want donations as a financial incentive. However, forcing users to open their wallet and copy-paste an address lowers the amount of people likely to send tokens (especially if they have to sync their wallet first).
If donating was as simple as clicking a link that opens a light wallet with pre-populated fields, users may be more willing to send tokens. URI schemes would enable users to easily make payments by simply clicking links on webpages or scanning QR Codes.
For stake pool URIs:
Centralised sources of information have led a growing amount of stake to be disproportionately assigned to pools pushed near & beyond the saturation point.
Stake pool URIs will provide an additional means for small pools to acquire delegation and maintain stability, supporting diversity and possibly fault-tolerance in the Cardano network through a more even distribution of stake.
Interfaces that connect delegators with pools beyond the highly contested top choices of the in-wallet ranking algorithms are important to avoid saturation and maintain decentralization.
Larger pools and collectives can also use these URIs to link to a family of pools they own to avoid any one of their pools becoming saturated.
Pool links allow for interfaces to initiate delegation transactions without requiring any code modifications to the wallets themselves.
The core implementation should follow the BIP-21 standard (with
bitcoin: replaced with
ada:as other projects that implement this standard tend to take the project name over the currency name (this makes sense if we consider this protocol as a generic way for interacting with the blockchain through wallets - as opposed to a simple payment system)
- Many wallets support multiple currencies. Following the same standard will ensure higher adoption of our protocol.
<a href="web+cardano:Ae2tdPwUPEZ76BjmWDTS7poTekAvNqBjgfthF92pSLSDVpRVnLP7meaFhVd">Donate</a> <a href="web+cardano://stake?c94e6fe1123bf111b77b57994bcd836af8ba2b3aa72cfcefbec2d3d4">Stake with us</a> <a href="web+cardano://stake?COSD">Choose our least saturated pool</a>
BIP-21 is limited to only features Bitcoin supports. A similar feature for Ethereum would, for example, also support gas as an extra parameter. BIP-21 is easily extensible but we have to take precaution to avoid different wallets having different implementations of these features as they become available on Cardano. To get an idea of some extra features that could be added, consider this (still under discussion) proposal for Ethereum: EIP-681
Depending on the protocol registration method (see next section), browsers generally enforce a
ext+prefix for non-whitelisted protocols (note:
bitcoin:was whitelisted). The prefix
ext+is recommended for extensions, but not mandatory.
ABNF Grammar (Proposal)
This is an initial, simplified protocol definition for fast implementation; it only requires:
- for a payment URI (authority unspecified), an address and an optional amount parameter;
- for a stake pool URI (authority =
stake), a single stake pool reference.
As discussed above, these rules are likely to evolve in time in order to support additional features, including multiple stake pool references (in proportions defining a "portfolio") and other unique capabilities of the Cardano blockchain.
cardanourn = "web+cardano:" (paymentref | stakepoolref) paymentref = cardanoaddress [ "?" amountparam ] cardanoaddress = *(base58 | bech32) amountparam = "amount=" *digit [ "." *digit ] stakepoolref = "//stake?" stakepool stakepool = poolhexid | poolticker poolhexid = 56HEXDIG poolticker = 3*5UNICODE
Payment URI queries
The amount parameter must follow the same rules described in BIP-21, namely, it must be specified in decimal ADA, without commas and using the period (.) decimal separator.
Stake pool URI queries
For brevity, essential in many Internet contexts,
poolticker must be supported here in addition to the unambiguous
When there is more than one pool registered with the specified
poolTicker (whether for pool groups which have the same ticker for all pools, or for separate pools using the same ticker), the choice to which pool to finally delegate is left to the user through the wallet UI.
Handling stake pool links
The wallet UI should always confirm the exact delegation choice even when it is unambiguous from the URI. When the user has multiple wallets, the wallet UI must select which wallet(s) the user will be delegating from.
These yet unsupported parameters in the URI query string should (by preference of the wallet UI designers) either be ignored or generate a warning message, to avoid leading the user to believe they are implementing a currently unsupported but perhaps popularly referenced multi-pool delegation list:
- any value for the first URI query argument;
- any URI query argument beyond the first.
- For payment links, we cannot prompt the user to send the funds right away as they may not be fully aware of the URI they clicked or were redirected to. Instead, it may be better to simply pre-populate fields in a transaction.
- For either payment or staking links, we should be wary of people who disguise links as actually opening up a phishing website that LOOKS like that corresponding part of the wallet UI.
Why not use Universal links, deep links and other non-protocol-based Solution
An alternative solution to the original problem described above is to use standard URL links in combination with a routing backend system. The routing system is used to redirect to the app's URI. The advantage of this scheme is that it allows to provide a fallback mechanism to handle the case when no application implementing the protocol is installed (for instance, by redirecting to the App Store or Google Play). This is the approach behind iOS Universal Links and Android App Links. In general, it provides a better user experience but requires a centralized system which makes it unsuitable for as a multi-app standard.