ARC-82: URI scheme blockchain information

Querying blockchain information using a URI format

Author	Barroso Stéphane
Discussions-To	https://github.com/algorandfoundation/ARCs/issues/324
Status	Last Call
Last Call Deadline	2025-02-15
Type	Standards Track
Category	ARC
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 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

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"
metadatahashparam  = "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.
• metadatahashparam (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/2345?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.

Citation

Please cite this document as:

Barroso Stéphane, "ARC-82: URI scheme blockchain information [DRAFT]," Algorand Requests for Comments, no. 82, November 2024. [Online serial]. Available: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0082.md.