ARC-62 - Integrate with ARC-54, ARC-89, and update reference implementation

ARCs/arc-0054.md

@@ -13,6 +13,7 @@ sub-category: Application
 created: 2023-09-15
 adoption-summary: adoption/arc-0054.yaml
 extended-by:
+  - 62
   - 89
 ---
 

ARCs/arc-0062.md

@@ -20,15 +20,16 @@ requires:
   - 2
   - 4
   - 22
+  - 54
 extended-by:
   - 89
 ---
 
 ## Abstract
 
 This ARC introduces a standard for the definition of circulating supply for Algorand
-Standard Assets (ASA) and its client-side retrieval. A reference implementation is
-suggested.
+Standard Assets (ASA) and its client-side retrieval. A reference implementation for
+a _singleton_ application is suggested.
 
 ## Motivation
 
@@ -108,9 +109,13 @@ App_ in this specification):
 The `arc62_get_circulating_supply` **MUST** be a _read-only_ ([ARC-22](./arc-0022.md))
 method (getter).
 
+### Burned Supply definition
+
+The _burned supply_ definition **MUST** comply with [ARC-54](./arc-0054.md#definitions-related-to-token-supply--burning).
+
 ### Usage
 
-Getter calls **SHOULD** be _simulated_.
+Getter calls by off-chain clients **SHOULD** be _simulated_.
 
 Any external resources used by the implementation **SHOULD** be discovered and
 auto-populated by the simulated getter call.
@@ -133,7 +138,7 @@ auto-populated by the simulated getter call.
 > ```
 >
 > In this case the simulated read-only method call would auto-populate 1 external
-> reference for the ASA and 3 external reference accounts (Reserve, Burned and Locked).
+> reference for the ASA and 3 external reference accounts (Reserve, Burned, and Locked).
 
 #### Example 2
 
@@ -162,10 +167,13 @@ An ASA conforming to this ARC **MUST** specify the Circulating Supply App ID.
 > the metadata of an ASA. Instead, it only extends already existing standards.
 
 If the ASA also conforms to any ARC that supports additional `properties` ([ARC-3](./arc-0003.md),
-[ARC-19](./arc-0019.md), etc.) as metadata declared in the ASA URL field,
+[ARC-89](./arc-0089.md), etc.) as metadata declared in the ASA URL field,
 then it **MUST** include a `arc-62` key and set the corresponding value to a map,
 including the ID of the Circulating Supply App as a value for the key `application-id`.
 
+It is **RECOMMENDED** to use the [ARC-89](./arc-0089.md) ASA Metadata Registry to
+declare support for this ARC and to discover the Circulating Supply App.
+
 #### Example: ARC-3 Property
 
 ```json
@@ -205,32 +213,71 @@ method for that ASA.
 
 ## Backwards Compatibility
 
-Existing ASA willing to conform to this ARC **MUST** specify the Circulating Supply
-App ID as [ARC-2](./arc-0002.md) `AssetConfig` transaction note field, as follows:
+Existing ASA willing to conform to this ARC **MUST** publish an [ARC-2](./arc-0002.md) message,
+to either:
 
-- The `<arc-number>` **MUST** be equal to `62`;
-- The **RECOMMENDED** `<data-format>` are <a href="https://msgpack.org/">MsgPack</a>
-(`m`) or <a href="https://www.json.org/json-en.html">JSON</a> (`j`);
-- The `<data>` **MUST** specify `application-id` equal to the Circulating Supply
-App ID.
+- (**RECOMMENDED**) Point clients to the [ASA metadata](#asa-circulating-supply-app-id-on-asa-metadata-registry)
+on the ASA Metadata Registry, or
+- (**NOT RECOMMENDED**) Provide the ASA Circulating Supply App ID [directly](#asa-circulating-supply-app-id-in-arc-2-note-field).
+
+As described in the subsections below.
+
+Clients discover the [ARC-2](./arc-0002.md) message inspecting the ASA `AssetConfig`
+transaction history.
+
+Clients **SHOULD** optimistically check ASA metadata existence on the ASA Metadata
+Registry first, to avoid inspecting the transaction history.
 
 > **WARNING**: To preserve the existing ASA RBAC (e.g. Manager Address, Freeze Address,
 > etc.) it is necessary to **include all the existing role addresses** in the `AssetConfig`.
 > Not doing so would irreversibly disable the RBAC roles!
 
-### Example - JSON without version
+### ASA Circulating Supply App ID on ASA Metadata Registry
 
-```text
-arc62:j{"application-id":123}
-```
+This is the **RECOMMENDED** option to specify the Circulating Supply App ID for an
+existing ASA.
+
+The ASA metadata **MUST** comply with the [ASA Circulating Supply discovery](#circulating-supply-application-discovery).
+
+For further details, refer to the ASA Metadata Registry [backward compatibility
+guidelines](./arc-0089.md#backwards-compatibility).
+
+### ASA Circulating Supply App ID in [ARC-2](./arc-0002.md) Note Field
+
+This option to specify the Circulating Supply App ID for an existing ASA is **NOT
+RECOMMENDED**, and was provided _before_ the availability of the ASA Metadata Registry
+(**RECOMMENDED**).
+
+- The `<arc-number>` **MUST** be equal to `62`;
+- The **RECOMMENDED** `<data-format>` are <a href="https://msgpack.org/">MsgPack</a>
+(`m`) or <a href="https://www.json.org/json-en.html">JSON</a> (`j`);
+- The `<data>` **MUST** specify `application-id` equal to the Circulating Supply
+App ID.
+
+> Example: JSON without a version
+>
+> ```text
+> arc62:j{"application-id":123}
+> ```
 
 ## Reference Implementation
 
 > This section is non-normative.
 
 This section suggests a reference implementation of the Circulating Supply App.
 
-An Algorand-Python example is [available](../assets/arc-0062).
+A [reference implementation](https://github.com/algorandfoundation/arc62) of a _singleton_
+ASA Circulating Supply App is maintained by the Algorand Foundation.
+
+The trusted deployments of the _singleton_ ASA Circulating Supply App are:
+
+| NETWORK  |            GENESIS HASH (`base64`)             |   APP ID    | CREATOR ADDRESS                                              |
+|:---------|:----------------------------------------------:|:-----------:|:-------------------------------------------------------------|
+| Main Net | `wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=` |    `TBD`    | `XODGWLOMKUPTGL3ZV53H3GZZWMCTJVQ5B2BZICFD3STSLA2LPSH6V6RW3I` |
+| Test Net | `SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=` | `755427327` | `Q3ROBYOB5QODCSNZKDYLH33NO5V4FN3YKMOHE43RPPC2LUPG56DNSU446I` |
+
+> Refer to the [ARC-56](./arc-0056.md) Application Specification of the [singleton
+> reference implementation](https://github.com/algorandfoundation/arc62/smart_contracts/artifacts/circulating_supply/CirculatingSupply.arc56.json).
 
 ### Recommendations
 
@@ -240,113 +287,85 @@ to the Circulating Supply App Account.
 A reference implementation **SHOULD** target a version of the AVM that supports
 foreign resources pooling (version 9 or greater).
 
-A reference implementation **SHOULD** use 3 external addresses, in addition to the
-Reserve Address, to define the not circulating supply.
+### Singleton Circulating Supply App
 
-> ⚠️The specification _is not limited_ to 3 external addresses. The implementations
-> **MAY** extend the non-circulating labels using more addresses, global storage,
-> box storage, etc.
+The _singleton_ reference implementation stores the ASA circulating supply configuration
+in a `CirculatingSupplyConfig` struct in box.
 
-The **RECOMMENDED** labels for not-circulating balances are: `burned`, `locked`
-and `generic`.
+#### Init Configuration
 
-> To change the labels of not circulating addresses is sufficient to rename the
-> following constants just in `smart_contracts/circulating_supply/config.py`:
->
-> ```python
-> NOT_CIRCULATING_LABEL_1: Final[str] = "burned"
-> NOT_CIRCULATING_LABEL_2: Final[str] = "locked"
-> NOT_CIRCULATING_LABEL_3: Final[str] = "generic"
-> ```
->
+To create the `CirculatingSupplyConfig` struct for an ASA:
 
-### State Schema
+- The authorization **MUST** be restricted to the ASA Manager Address;
 
-A reference implementation **SHOULD** allocate, at least, the following Global State
-variables:
+- The `CirculatingSupplyConfig` struct **MUST NOT** exist for the ASA;
 
-- `asset_id` as UInt64, initialized to `0` and set **only once** by the ASA Manager
-Address;
-- Not circulating address 1 (`burned`) as Bytes, initialized to the Global `Zero Address`
- and set by the ASA Manager Address;
-- Not circulating address 2 (`locked`) as Bytes, initialized to the Global `Zero Address`
-and set by the ASA Manager Address;
-- Not circulating address 3 (`generic`) as Bytes, initialized to the Global `Zero Address`
-and set by the ASA Manager Address.
+- The `CirculatingSupplyConfig` struct MBR **MUST** be provided contextually.
 
-A reference implementation **SHOULD** enforce that, upon setting `burned`, `locked`
-and `generic` addresses, the latter already opted-in the `asset_id`.
+The addresses of `CirculatingSupplyConfig` struct **MUST** be initialized to the
+`ZeroAddress`.
 
-```json
-"state": {
-    "global": {
-        "num_byte_slices": 3,
-        "num_uints": 1
-    },
-    "local": {
-        "num_byte_slices": 0,
-        "num_uints": 0
-    }
-},
-"schema": {
-    "global": {
-        "declared": {
-            "asset_id": {
-                "type": "uint64",
-                "key": "asset_id"
-            },
-            "not_circulating_label_1": {
-                "type": "bytes",
-                "key": "burned"
-            },
-            "not_circulating_label_2": {
-                "type": "bytes",
-                "key": "locked"
-            },
-            "not_circulating_label_3": {
-                "type": "bytes",
-                "key": "generic"
-            }
-        },
-        "reserved": {}
-    },
-    "local": {
-        "declared": {},
-        "reserved": {}
-    }
-},
-```
+The `CirculatingSupplyConfig` struct MBR **MUST** be returned.
+
+> This method can be simulated to discover the `CirculatingSupplyConfig` struct MBR.
+
+#### Set Not Circulating Addresses
+
+To set a not-circulating `address` for an ASA:
+
+- The authorization **MUST** be restricted to the ASA Manager Address;
+
+- The `CirculatingSupplyConfig` struct **MUST** exist for the ASA;
+
+- The not-circulating label **MUST** be one of:
+  - `burned`,
+  - `custom_1`,
+  - `custom_2`,
+  - `custom_3`,
+  - `custom_4`.
+
+- The not-circulating `address` **MUST** be opted in to ASA.
+
+If the not-circulating label is `burned`:
+
+- The ASA **MUST NOT** have a Clawback Address, and
+
+- The address **MUST** be assigned to the [ARC-54 ASA Burning App](./arc-0054.md#deployments).
+
+The `address` **MUST** be set in the `CirculatingSupplyConfig` struct.
+
+#### Delete Configuration
+
+To delete the `CirculatingSupplyConfig` struct for an ASA:
+
+- The `CirculatingSupplyConfig` struct **MUST** exist for the ASA;
+
+- If the ASA still _exists_:
+
+  - The authorization **MUST** be restricted to the ASA Manager Address.
 
-### Circulating Supply Getter
+The `CirculatingSupplyConfig` struct **MUST** be deleted.
 
-A reference implementation **SHOULD** enforce that the `asset_id` Global Variable
-is equal to the `asset_id` argument of the `arc62_get_circulating_supply` getter
-method.
+The `CirculatingSupplyConfig` struct MBR **MUST** be returned contextually to the
+caller.
 
-> Alternatively the reference implementation could ignore the `asset_id` argument
-> and use directly the `asset_id` Global Variable.
+#### Get Circulating Supply
 
-A reference implementation **SHOULD** return the ASA _circulating supply_ as:
+The _singleton_ reference implementation returns the ASA _circulating supply_ as:
 
 ```text
-circulating_supply = total - reserve_balance - burned_balance - locked_balance - generic_balance
+circulating_supply = total - reserve_balance - burned_balance - custom_balances (1 ... 4)
 ```
 
 Where:
 
 - `total` is the total supply of the ASA (`asset_id`);
 - `reserve_balance` is the ASA balance hold by the Reserve Address or `0` if the
-address is set to the Global `ZeroAddress` or not opted-in `asset_id`;
+address is set to the Global `ZeroAddress`, not opted-in `asset_id`, or the ASA does not exist;
 - `burned_balance` is the ASA balance hold by the Burned Address or `0` if the address
-is set to the Global `ZeroAddress` or is not opted-in `asset_id`;
-- `locked_balance` is the ASA balance hold by the Locked Address or `0` if the address
-is set to the Global `ZeroAddress` or not opted-in `asset_id`;
-- `generic_balance` is the ASA balance hold by a Generic Address or `0` if the address
-is set to the Global `ZeroAddress` or not opted-in `asset_id`.
-
-> ⚠️The implementations **MAY** extend the calculation of `circulating_supply` using
-> global storage, box storage, etc. See [Example 2](./arc-0062.md#example-2) for
-> reference.
+is set to the Global `ZeroAddress`, is not opted-in `asset_id`, or the ASA does not exist;
+- `custom_balance` (`1 ... 4`) is the ASA balance hold by a Custom Address `N` or `0` if the address
+is set to the Global `ZeroAddress`, not opted-in `asset_id`, or the ASA does not exist.
 
 ## Security Considerations