diff --git a/ARCs/arc-0080.md b/ARCs/arc-0080.md new file mode 100644 index 000000000..0d7611962 --- /dev/null +++ b/ARCs/arc-0080.md @@ -0,0 +1,147 @@ +--- +arc: 80 +title: URI scheme blockchain information +description: Querying blockchain information using a URI format +author: Barroso Stéphane (@sudoweezy) +discussions-to: https://github.com/algorandfoundation/ARCs/issues/324 +status: Draft +type: Standards Track +category: ARC +sub-category: General +created: 2024-11-13 +--- + +## Abstract + +This URI specification defines a standardized method for querying application and asset data on Algorand. +It enables applications, websites, and QR code implementations to construct URIs that allow users to retrieve data such as application state and asset metadata in a structured format. +This specification is inspired by [ARC-26](./arc-0026.md) and follows similar principles, with adjustments specific to read-only queries for applications and assets. + +## Specification + +### General Format + +Algorand URIs in this standard follow the general format for URIs as defined in RFC 3986. +The scheme component specifies whether the URI is querying an application (`algorand:app://`) or an asset (`algorand:asset://`). +Query parameters define the specific data fields being requested. +Parameters may contain characters outside the valid range. These must first be encoded in UTF-8, then percent-encoded according to RFC 3986. + +### Application Query URI (`algorand:app://`) + +The application URI allows querying the state of an application, including data from the application’s box storage, global storage, and local storage. +And the teal program associated. +Each storage type has specific requirements. + +### Asset Query URI (`algorand:asset://`) + +The asset URI enables retrieval of metadata and configuration details for a specific asset, such as its name, total supply, decimal precision, and associated addresses. + +### ABNF Grammar + +```abnf +algorandappurn = "algorand:app://" appid [ "?" noopparams ] +appid = *digit +noopparams = noopparam [ "&" noopparams ] +noopparam = [ boxparam / globalparam / localparam ] +boxparam = "box=" *qbase64url +globalparam = "global=" *qbase64url +localparam = "local=" *qbase64url "&algorandaddress=" *base32 +tealcodeparam = "tealcode" + +algorandasseturn = "algorand:asset://" assetid [ "?" assetparam ] +assetid = *digit +assetparam = [ totalparam / decimalsparam / frozenparam / unitnameparam / assetnameparam / urlparam / hashparam / managerparam / reserveparam / freezeparam / clawbackparam ] +totalparam = "total" +decimalsparam = "decimals" +frozenparam = "frozen" +unitnameparam = "unitname" +assetnameparam = "assetname" +urlparam = "url" +hashparam = "metadatahash" +managerparam = "manager" +reserveparam = "reserve" +freezeparam = "freeze" +clawbackparam = "clawback" +``` + +### Parameter Definitions + +#### Application Parameters + +- **`boxparam`**: Queries the application’s box storage with a key encoded in `base64url`. +- **`globalparam`**: Queries the global storage of the application using a `base64url`-encoded key. +- **`localparam`**: Queries local storage for a specified account. Requires an additional `algorandaddress` parameter, representing the account whose local storage is queried. + +#### Asset Parameters + +- **`totalparam`** (`total`): Queries the total supply of the asset. +- **`decimalsparam`** (`decimals`): Queries the number of decimal places used for the asset. +- **`frozenparam`** (`frozen`): Queries whether the asset is frozen by default. +- **`unitnameparam`** (`unitname`): Queries the short name or unit symbol of the asset (e.g., "USDT"). +- **`assetnameparam`** (`assetname`): Queries the full name of the asset (e.g., "Tether"). +- **`urlparam`** (`url`): Queries the URL associated with the asset, providing more information. +- **`hashparam`** (`metadatahash`): Queries the metadata hash associated with the asset. +- **`managerparam`** (`manager`): Queries the address of the asset manager. +- **`reserveparam`** (`reserve`): Queries the reserve address holding non-minted units of the asset. +- **`freezeparam`** (`freeze`): Queries the freeze address for the asset. +- **`clawbackparam`** (`clawback`): Queries the clawback address for the asset. + +### Query Key Descriptions + +For each parameter, the query key name is listed, followed by its purpose: + +- **box**: Retrieves information from the specified box storage key. +- **global**: Retrieves data from the specified global storage key. +- **local**: Retrieves data from the specified local storage key. Requires `algorandaddress` to specify the account. +- **total**: Retrieves the asset's total supply. +- **decimals**: Retrieves the number of decimal places for the asset. +- **frozen**: Retrieves the default frozen status of the asset. +- **unitname**: Retrieves the asset’s short name or symbol. +- **assetname**: Retrieves the full name of the asset. +- **url**: Retrieves the URL associated with the asset. +- **metadatahash**: Retrieves the metadata hash for the asset. +- **manager**: Retrieves the manager address of the asset. +- **reserve**: Retrieves the reserve address for the asset. +- **freeze**: Retrieves the freeze address of the asset. +- **clawback**: Retrieves the clawback address of the asset. + +### Example URIs + +1. **Querying an Application’s Box Storage**: + ``` + algorand:app://12345?box=YWxnb3JvbmQ= + ``` + Queries box storage with a `base64url`-encoded key. + +2. **Querying Global Storage**: + ``` + algorand:app://12345?global=Z2xvYmFsX2tleQ== + ``` + Queries global storage with a `base64url`-encoded key. + +3. **Querying Local Storage**: + ``` + algorand:app://12345?local=bG9jYWxfa2V5&algorandaddress=ABCDEFGHIJKLMNOPQRSTUVWXYZ234567 + ``` + Queries local storage with a `base64url`-encoded key and specifies the associated account. + +4. **Querying Asset Details**: + ``` + algorand:asset://67890?total + ``` + Queries the total supply of an asset. + + +## Rationale + +Previously, the Algorand URI scheme was primarily used to create transactions on the chain. +This version allows using a URI scheme to directly retrieve information from the chain, specifically for applications and assets. +This URI scheme provides a unified, standardized method for querying Algorand application and asset data, allowing interoperability across applications and services. + +## Security Considerations + +Since these URIs are intended for read-only operations, they do not alter application or asset state, mitigating many security risks. However, data retrieved from these URIs should be validated to ensure it meets user expectations and that any displayed data cannot be tampered with. + +## Copyright + +Copyright and related rights waived via CCO.