diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 9cc47a5cd..70dad15a7 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -13,7 +13,7 @@ jobs: save-pr: name: Save PR Number runs-on: ubuntu-latest - + steps: - name: Save PR number env: @@ -34,28 +34,28 @@ jobs: htmlproofer: name: HTMLProofer runs-on: ubuntu-latest - + steps: - name: Checkout ARC Repository uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b - + - name: Install OpenSSL run: sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev - + - name: Install Ruby uses: ruby/setup-ruby@0a29871fe2b0200a17a4497bae54fe5df0d973aa with: ruby-version: 2.6.0 bundler-cache: true - + - name: Build Website run: | bundle exec jekyll doctor bundle exec jekyll build - + - name: HTML Proofer run: bundle exec htmlproofer ./_site --check-html --check-opengraph --report-missing-names --log-level=:debug --assume-extension --empty-alt-ignore --timeframe=6w --disable-external - + - name: DNS Validator run: bundle exec github-pages health-check diff --git a/.github/workflows/dev-portal-content.yml b/.github/workflows/dev-portal-content.yml new file mode 100644 index 000000000..5b45d12df --- /dev/null +++ b/.github/workflows/dev-portal-content.yml @@ -0,0 +1,67 @@ +name: Create Dev Portal Content + +on: + push: + branches: + - main # Trigger on changes to the main branch + paths: + - "ARCs/**" # Only run when files in the ARCs directory are changed + +jobs: + updateDevportal: + runs-on: ubuntu-latest + + steps: + # Step 1: Checkout the repository + - name: Checkout code + uses: actions/checkout@v2 + + # Step 2: Set execute permission for the scripts and create the content directory if needed + - name: Make scripts executable + run: | + chmod +x _devportal/scripts/update-arcs.sh + chmod +x _devportal/scripts/update-guideline.sh + chmod +x _devportal/scripts/update-index.sh + mkdir -p _devportal/content + + # Step 3: Set up Git identity + - name: Set up Git user + run: | + git config --global user.name 'github-actions' + git config --global user.email 'github-actions@github.com' + + # Step 4: Run update-arcs.sh script + - name: Run update-arcs.sh + run: _devportal/scripts/update-arcs.sh + + # Step 5: Run update-guideline.sh script + - name: Run update-guideline.sh + run: _devportal/scripts/update-guideline.sh + + # Step 6: Run update-index.sh script + - name: Run update-index.sh + run: _devportal/scripts/update-index.sh + + # Step 7: Force changes to be recognized by Git + - name: Touch modified files + run: | + find _devportal/content -type f -exec touch {} \; + + # Step 8: Commit and force push changes to devportal + - name: Commit and force push changes to devportal + run: | + git add -A # Ensure all changes are staged + git add -f _devportal/content/* + git commit -m "Auto-update ARC content and headers" + BRANCH_NAME="devportal" + + # Check if the branch exists on the remote + if git ls-remote --exit-code --heads origin "$BRANCH_NAME"; then + echo "Branch $BRANCH_NAME exists on the remote. Force pushing updates." + git push origin main:"$BRANCH_NAME" --force # Corrected force push from main to devportal + else + echo "Branch $BRANCH_NAME does not exist. Creating it and pushing." + git push origin main:"$BRANCH_NAME" --force # Create the branch and force push + fi + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index 0eacddc03..c24da7b5c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ vendor .bundle -_site/* \ No newline at end of file +_site/* +_devportal/content/*.md diff --git a/ARC-template.md b/ARC-template.md index 0823ab2d7..5d91825ec 100644 --- a/ARC-template.md +++ b/ARC-template.md @@ -7,6 +7,7 @@ discussions-to: status: Draft type: category (*only required for Standards Track): +subcategory: created: requires (*optional): --- @@ -15,7 +16,7 @@ This is the suggested template for new ARCs. Note that an ARC number will be assigned by an editor. When opening a pull request to submit your ARC, please use an abbreviated title in the filename, `arc-draft_title_abbrev.md`. -The title should be 44 characters or less. It should not repeat the ARC number in title, irrespective of the category. +The title should be 44 characters or less. It should not repeat the ARC number in title, irrespective of the category. ## Abstract Abstract is a multi-sentence (short paragraph) technical summary. This should be a very terse and human-readable version of the specification section. Someone should be able to read only the abstract to get the gist of what this specification does. diff --git a/ARCs/arc-0000.md b/ARCs/arc-0000.md index f76249d25..ece37728c 100644 --- a/ARCs/arc-0000.md +++ b/ARCs/arc-0000.md @@ -1,11 +1,12 @@ --- arc: 0 title: ARC Purpose and Guidelines -description: Guide explaning how to write a new ARC +description: Guide explaining how to write a new ARC author: Ben Guidarelli (@barnjamin), Stéphane Barroso (@sudoweezy) discussions-to: https://github.com/algorandfoundation/ARCs/issues/9 status: Living type: Meta +sub-category: General created: 2021-10-28 --- @@ -17,14 +18,14 @@ ARC stands for Algorand Request for Comments. An ARC is a design document provid The ARC should provide a concise technical specification and a rationale for the feature. The ARC author is responsible for building consensus within the community and documenting dissenting opinions. -We intend ARCs to be the primary mechanisms for proposing new features and collecting community technical input on an issue. +We intend ARCs to be the primary mechanisms for proposing new features and collecting community technical input on an issue. We maintain ARCs as text files in a versioned repository. Their revision history is the historical record of the feature proposal. ## Specification ### ARC Types -There are three types of ARC: +There are three types of ARC: - A **Standards track ARC**: application-level standards and conventions, including contract standards such as NFT standards, Algorand ABI, URI schemes, library/package formats, and wallet formats. @@ -235,7 +236,7 @@ This document was derived heavily from An early draft of this ARC required that the size of a group of transactions must be greater than 1 but, since the Algorand protocol supports groups of size 1, this requirement had been changed so dApps don't have to have special cases for single transactions and can always send a group to the wallet. 2. (**OPTIONAL**) `txns` is a concatenation of `txns` arrays of transactions of type 1: - * All transactions with the *same* non-zero group ID must be consecutive and must match their group ID. The wallet **MUST** reject if the above is not satisfied. + * All transactions with the *same* non-zero group ID must be consecutive and must match their group ID. The wallet **MUST** reject if the above is not satisfied. * The wallet UI **MUST** be designed so that it is clear to the user when transactions are grouped (aka form an atomic transfers) and when they are not. It **SHOULD** provide very clear explanations that are understandable by beginner users, so that they cannot easily be tricked to sign what they believe is an atomic exchange while it is in actuality a one-sided payment. If `txns` does not match any of the formats above, the wallet **MUST** reject. @@ -341,12 +342,12 @@ The wallet **MAY** choose to restrict the maximum size of the array `txns`. The An early draft of this API allowed to sign single transactions in a group without providing the other transactions in the group. For security reasons, this use case is now deprecated and **SHALL** not be allowed in new implementations. Existing implementations may continue allowing for single transactions to be signed if a very clear warning is displayed to the user. The warning **MUST** stress that signing the transaction may incur losses that are much higher than the amount of tokens indicated in the transaction. That is because potential future features of Algorand may later have such consequences (e.g., a signature of a transaction may actually authorize the full group under some circumstances). -#### Transaction Validation +#### Transaction Validation ##### Inputs that Must Be Systematically Rejected * Transactions `WalletTransaction.txn` with fields that are not known by the wallet **MUST** be systematically rejected. In particular: - * Every field **MUST** be validated. + * Every field **MUST** be validated. * Any extra field **MUST** systematically make the wallet reject. * This is to prevent any security issue in case of the introduction of new dangerous fields (such as `txn.RekeyTo` or `txn.CloseRemainderTo`). * Transactions of an unknown type (field `txn.Type`) **MUST** be rejected. @@ -404,7 +405,7 @@ The last two items are expected to be defined in other documents. The requirements around group validation have been designed to prevent the following attack. -The dApp pretends to buy 1 Algo for 10 USDC, but instead creates an atomic transfer with the user sending 1 Algo to the dApp and the dApp sending 0.01 USDC to the user. However, it sends to the wallet a 1 Algo and 10 USDC transactions. +The dApp pretends to buy 1 Algo for 10 USDC, but instead creates an atomic transfer with the user sending 1 Algo to the dApp and the dApp sending 0.01 USDC to the user. However, it sends to the wallet a 1 Algo and 10 USDC transactions. If the wallet does not verify that this is a valid group, it will make the user believe that they are signing for the correct atomic transfer. diff --git a/ARCs/arc-0002.md b/ARCs/arc-0002.md index c1abe6b3a..9cbc8a6d2 100644 --- a/ARCs/arc-0002.md +++ b/ARCs/arc-0002.md @@ -2,11 +2,12 @@ arc: 2 title: Algorand Transaction Note Field Conventions description: Conventions for encoding data in the note field at application-level -author: Fabrice Benhamouda (@fabrice102) +author: Fabrice Benhamouda (@fabrice102), Stéphane Barroso (@SudoWeezy), Cosimo Bassi (@cusma) discussions-to: https://github.com/algorandfoundation/ARCs/issues/2 status: Final type: Standards Track category: ARC +sub-category: Explorer created: 2021-07-06 --- @@ -20,10 +21,16 @@ The goal of these conventions is to make it simpler for block explorers and inde Note fields should be formatted as follows: +for dApps ``` : ``` +for ARCs +``` +arc: +``` + where: * `` is the name of the dApp: * Regexp to satisfy: `[a-zA-Z0-9][a-zA-Z0-9_/@.-]{4-31}` @@ -33,6 +40,12 @@ where: * be at least 5 characters long * be at most 32 characters long * Names starting with `a/` and `af/` are reserved for the Algorand protocol and the Algorand Foundation uses. + +* `` is the number of the ARC: + * Regexp to satisfy: `\b(0|[1-9]\d*)\b` + In other words, an arc-number should: + * Only contain a digit number, without any padding + * `` is one of the following: * `m`: MsgPack * `j`: JSON @@ -40,7 +53,9 @@ where: * `u`: utf-8 string * `` is the actual data in the format specified by `` -**WARNING**: Any user can create transactions with arbitrary data and may impersonate other dApps. In particular, the fact that a note field start with `` does not guarantee that it indeed comes from this dApp. The value `` cannot be relied upon to ensure provenance and validity of the ``. +**WARNING**: Any user can create transactions with arbitrary data and may impersonate other dApps. In particular, the fact that a note field start with `` does not guarantee that it indeed comes from this dApp. The value `` cannot be relied upon to ensure provenance and validity of the ``. + +**WARNING**: Any user can create transactions with arbitrary data, including ARC numbers, which may not correspond to the intended standard. An ARC number included in a note field does not ensure compliance with the corresponding standard. The value of the ARC number cannot be relied upon to ensure the provenance and validity of the . ### Versioning @@ -73,7 +88,16 @@ The restrictions on dApp names were chosen to allow most usual names while avoid > This section is non-normative. -Consider a dApp named `algoCityTemp` that stores temperatures from cities on the blockchain. +Consider [ARC-20](./arc-0020.md), that provides information about Smart ASA's Application. + +Here a potential note indicating that the Application ID is 123: + +* JSON without version: + ``` + arc20:j{"application-id":123} + ``` + +Consider a dApp named `algoCityTemp` that stores temperatures from cities on the blockchain. Here are some potential notes indicating that Singapore's temperature is 35 degree Celsius: * JSON without version: @@ -111,4 +135,4 @@ Here are some potential notes indicating that Singapore's temperature is 35 degr ## Copyright -Copyright and related rights waived via CCO. \ No newline at end of file +Copyright and related rights waived via CCO. diff --git a/ARCs/arc-0003.md b/ARCs/arc-0003.md index deedf46f6..746a4c3a8 100644 --- a/ARCs/arc-0003.md +++ b/ARCs/arc-0003.md @@ -7,6 +7,7 @@ discussions-to: https://github.com/algorandfoundation/ARCs/issues/3 status: Final type: Standards Track category: ARC +sub-category: Asa created: 2021-08-07 --- @@ -36,7 +37,7 @@ The ASA parameters should follow the following conventions: * If the resulting asset name can fit the *Asset Name* field, then `` **SHOULD** be equal to the name in the JSON Metadata file. * If the resulting asset name cannot fit the *Asset Name* field, then `` **SHOULD** be a reasonable shorten version of the name in the JSON Metadata file. * (**RECOMMENDED**) or `` where `` is defined as above. In this case, the Asset URL **MUST** end with `#arc3`. -* *Asset URL* (`au`): a URI pointing to a JSON Metadata file. +* *Asset URL* (`au`): a URI pointing to a JSON Metadata file. * This URI as well as any URI in the JSON Metadata file: * **SHOULD** be persistent and allow to download the JSON Metadata file forever. * **MAY** contain the string `{id}`. If `{id}` exists in the URI, clients **MUST** replace this with the asset ID in decimal form. The rules below applies after such a replacement. @@ -44,18 +45,18 @@ The ASA parameters should follow the following conventions: * **SHOULD** use one of the following URI schemes (for compatibility and security): *https* and *ipfs*: * When the file is stored on IPFS, the `ipfs://...` URI **SHOULD** be used. IPFS Gateway URI (such as `https://ipfs.io/ipfs/...`) **SHOULD NOT** be used. * **SHOULD NOT** use the following URI scheme: *http* (due to security concerns). - * **MUST** be such that the returned resource includes the CORS header + * **MUST** be such that the returned resource includes the CORS header ``` Access-Control-Allow-Origin: * ``` if the URI scheme is *https* > This requirement is to ensure that client JavaScript can load all resources pointed by *https* URIs inside an ARC-3 ASA. * **MAY** be a relative URI when inside the JSON Metadata file. In that case, the relative URI is relative to the Asset URL. The Asset URL **SHALL NOT** be relative. Relative URI **MUST** not contain the character `:`. Clients **MUST** consider a URI as relative if and only if it does not contain the character `:`. - * If the Asset Name is neither `arc3` nor of the form `@arc3`, then the Asset URL **MUST** end with `#arc3`. + * If the Asset Name is neither `arc3` nor of the form `@arc3`, then the Asset URL **MUST** end with `#arc3`. * If the Asset URL ends with `#arc3`, clients **MUST** remove `#arc3` when linking to the URL. When displaying the URL, they **MAY** display `#arc3` in a different style (e.g., a lighter color). * If the Asset URL ends with `#arc3`, the full URL with `#arc3` **SHOULD** be valid and point to the same resource as the URL without `#arc3`. - > This recommendation is to ensure backward compatiblity with wallets that do not support ARC-3. -* *Asset Metadata Hash* (`am`): + > This recommendation is to ensure backward compatibility with wallets that do not support ARC-3. +* *Asset Metadata Hash* (`am`): * If the JSON Metadata file specifies extra metadata `e` (property `extra_metadata`), then `am` is defined as: ```plain @@ -76,7 +77,7 @@ There are no requirements regarding the manager account of the ASA, or its the r An ASA is said to be a *pure non-fungible token* (*pure NFT*) if and only if it has the following properties: -* *Total Number of Units* (`t`) **MUST** be 1. +* *Total Number of Units* (`t`) **MUST** be 1. * *Number of Digits after the Decimal Point* (`dc`) **MUST** be 0. An ASA is said to be a *fractional non-fungible token* (*fractional NFT*) if and only if it has the following properties: @@ -444,7 +445,7 @@ Note that if the base metadata file URI (i.e., the Asset URL) is `ipfs://QmWS1VA ## Rationale -These conventions are heavily based on Ethereum Improvement Proposal ERC-1155 Metadata URI JSON Schema to facilitate interoperobility. +These conventions are heavily based on Ethereum Improvement Proposal ERC-1155 Metadata URI JSON Schema to facilitate interoperobility. The main differences are highlighted below: diff --git a/ARCs/arc-0004.md b/ARCs/arc-0004.md index 08fcfffe6..ba8b87ca2 100644 --- a/ARCs/arc-0004.md +++ b/ARCs/arc-0004.md @@ -7,6 +7,7 @@ discussions-to: https://github.com/algorandfoundation/ARCs/issues/44 status: Final type: Standards Track category: Interface +sub-category: Application created: 2021-07-29 --- @@ -16,15 +17,15 @@ created: 2021-07-29 This document introduces conventions for encoding method calls, including argument and return value encoding, in Algorand Application -call transactions. +call transactions. The goal is to allow clients, such as wallets and -dapp frontends, to properly encode call transactions based on a description +dapp frontends, to properly encode call transactions based on a description of the interface. Further, explorers will be able to show details of these method invocations. ### Definitions -* **Application:** an Algorand Application, aka "smart contract", +* **Application:** an Algorand Application, aka "smart contract", "stateful contract", "contract", or "app". * **HLL:** a higher level language that compiles to TEAL bytecode. * **dapp (frontend)**: a decentralized application frontend, interpreted here to @@ -41,7 +42,7 @@ The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL > Comments like this are non-normative. -Interfaces are defined in TypeScript. All the objects that are defined +Interfaces are defined in TypeScript. All the objects that are defined are valid JSON objects, and all JSON `string` types are UTF-8 encoded. ### Overview @@ -52,7 +53,7 @@ access by higher-level entities. Encoding recommendations are intended to be minimal, intended only to allow interoperability among Applications. Higher level recommendations are intended to enhance user-facing interfaces, such as high-level languages, dapps, and -wallets. Applications that follow the recommendations described here are +wallets. Applications that follow the recommendations described here are called _[ARC-4](./arc-0004.md) Applications_. ### Methods @@ -83,9 +84,9 @@ method's signature, and **MUST NOT** contain any whitespace. For example, `add(uint64,uint64)uint128` is the method signature for a method named `add` which takes two uint64 parameters and returns a -uint128. Signatures are encoded in ASCII. +uint128. Signatures are encoded in ASCII. -For the benefit of universal interoperability (especially in HLLs), +For the benefit of universal interoperability (especially in HLLs), names **MUST** satisfy the regular expression `[_A-Za-z][A-Za-z0-9_]*`. Names starting with an underscore are reserved and **MUST** only be used as specified in this ARC or future ABI-related ARC. @@ -172,19 +173,19 @@ For example: An Interface is a logically grouped set of methods. All method selectors in an Interface **MUST** be unique. Method names **MAY** not be unique, as long as -the corresponding method selectors are different. Method names in Interfaces +the corresponding method selectors are different. Method names in Interfaces **MUST NOT** begin with an underscore. An Algorand Application *implements* an Interface if it supports all of the methods from that Interface. An Application **MAY** implement zero, one, or multiple Interfaces. -Interface designers **SHOULD** try to prevent collisions of method selectors -between Interfaces that are likely to be implemented together by the same +Interface designers **SHOULD** try to prevent collisions of method selectors +between Interfaces that are likely to be implemented together by the same Application. > For example, an Interface `Calculator` providing addition and subtraction -> of integer methods and an Interface `NumberFormating` providing formatting +> of integer methods and an Interface `NumberFormatting` providing formatting > methods for numbers into strings are likely to be used together. > Interface designers should ensure that all the methods in `Calculator` and > `NumberFormatting` have distinct method selectors. @@ -368,9 +369,9 @@ interface Contract { Contract names **MUST** satisfy the regular expression `[_A-Za-z][A-Za-z0-9_]*`. -The `desc` fields of the Contract and the methods inside the Contract -**SHOULD** contain informations that is not explicitly encoded in the other fields, -such as support of bare Application calls, requirement of specific +The `desc` fields of the Contract and the methods inside the Contract +**SHOULD** contain information that is not explicitly encoded in the other fields, +such as support of bare Application calls, requirement of specific OnCompletion action for specific methods, and methods to call for creation (if creation cannot be done via a bare Application call). @@ -439,8 +440,8 @@ be encoded as defined in the [Encoding](#encoding) section. If a method has a non-void return type, then the return value of the method **MUST** be located in the final logged value of the method's execution, using the `log` opcode. The logged value **MUST** contain a specific 4 byte -prefix, followed by the encoding of the return value as defined in the -[Encoding](#encoding) section. The 4 byte prefix is defined as the first 4 +prefix, followed by the encoding of the return value as defined in the +[Encoding](#encoding) section. The 4 byte prefix is defined as the first 4 bytes of the SHA-512/256 hash of the ASCII string `return`. In hex, this is `151f7c75`. @@ -684,10 +685,10 @@ a client would create a transaction group containing, in this order: 2. a payment 3. the actual Application call -When encoding the other (non-transaction) arguments, the client -**MUST** act as if the transaction arguments were completely absent -from the method signature. The Application call would contain the method -selector in ApplicationArgs[0], the first (string) argument in +When encoding the other (non-transaction) arguments, the client +**MUST** act as if the transaction arguments were completely absent +from the method signature. The Application call would contain the method +selector in ApplicationArgs[0], the first (string) argument in ApplicationArgs[1], and the fourth (uint32) argument in ApplicationArgs[2]. @@ -697,12 +698,12 @@ they can do so safely. For example, they **SHOULD** use `gtxns` to examine the previous index in the group for a required `pay` transaction, rather than hardcode an index with `gtxn`. -In general, an ARC-4 Application method with `n` transactions as arguments **SHOULD** +In general, an ARC-4 Application method with `n` transactions as arguments **SHOULD** only inspect the `n` previous transactions. In particular, it **SHOULD NOT** -inspect transactions after and it **SHOULD NOT** check the size of a transaction -group (if this can be done safely). +inspect transactions after and it **SHOULD NOT** check the size of a transaction +group (if this can be done safely). In addition, a given method **SHOULD** always expect the same -number of transactions before itself. For example, the method +number of transactions before itself. For example, the method `deposit(string,axfer,pay,uint32)void` is always preceded by two transactions. It is never the case that it can be called only with one asset transfer but no payment transfer. @@ -721,4 +722,4 @@ None. ## Copyright -Copyright and related rights waived via CCO. \ No newline at end of file +Copyright and related rights waived via CCO. diff --git a/ARCs/arc-0005.md b/ARCs/arc-0005.md index c6be63eac..da9632d1b 100644 --- a/ARCs/arc-0005.md +++ b/ARCs/arc-0005.md @@ -7,6 +7,7 @@ discussions-to: https://github.com/algorandfoundation/ARCs/issues/52 status: Final type: Standards Track category: Interface +sub-category: Wallet created: 2021-08-09 --- @@ -31,7 +32,7 @@ The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL ### Interface `SignTxnsFunction` -Signatures are requested by calling a function `signTxns(txns)` on a list `txns` of transactions. The dApp may also provide an optional parameter `opts`. +Signatures are requested by calling a function `signTxns(txns)` on a list `txns` of transactions. The dApp may also provide an optional parameter `opts`. A wallet transaction signing function `signTxns` is defined by the following interface: ```ts @@ -86,4 +87,4 @@ None. ## Copyright -Copyright and related rights waived via CCO. \ No newline at end of file +Copyright and related rights waived via CCO. diff --git a/ARCs/arc-0006.md b/ARCs/arc-0006.md index 56075f2f9..8dd478d47 100644 --- a/ARCs/arc-0006.md +++ b/ARCs/arc-0006.md @@ -4,10 +4,11 @@ title: Algorand Wallet Address Discovery API description: API function, enable, which allows the discovery of accounts author: DanBurton (@DanBurton) discussions-to: https://github.com/algorandfoundation/ARCs/issues/52 -status: Final +status: Deprecated type: Standards Track category: Interface created: 2021-08-09 +superseded-by: --- # Algorand Wallet Address Discovery API diff --git a/ARCs/arc-0007.md b/ARCs/arc-0007.md index 4f971d8f5..6bd2696a9 100644 --- a/ARCs/arc-0007.md +++ b/ARCs/arc-0007.md @@ -4,10 +4,11 @@ title: Algorand Wallet Post Transactions API description: API function to Post Signed Transactions to the network. author: DanBurton (@DanBurton) discussions-to: https://github.com/algorandfoundation/ARCs/issues/52 -status: Final +status: Deprecated type: Standards Track category: Interface created: 2021-08-09 +superseded-by: --- # Algorand Wallet Post Transactions API diff --git a/ARCs/arc-0008.md b/ARCs/arc-0008.md index c51b1f432..cbf7f5cb4 100644 --- a/ARCs/arc-0008.md +++ b/ARCs/arc-0008.md @@ -4,10 +4,11 @@ title: Algorand Wallet Sign and Post API description: A function used to simultaneously sign and post transactions to the network. author: DanBurton (@DanBurton) discussions-to: https://github.com/algorandfoundation/ARCs/issues/52 -status: Final +status: Deprecated type: Standards Track category: Interface created: 2021-08-09 +superseded-by: --- # Algorand Wallet Sign and Post API diff --git a/ARCs/arc-0009.md b/ARCs/arc-0009.md index afed84691..b60dfcbf7 100644 --- a/ARCs/arc-0009.md +++ b/ARCs/arc-0009.md @@ -4,10 +4,11 @@ title: Algorand Wallet Algodv2 and Indexer API description: An API for accessing Algod and Indexer through a user's preferred connection. author: DanBurton (@DanBurton) discussions-to: https://github.com/algorandfoundation/ARCs/issues/52 -status: Final +status: Deprecated type: Standards Track category: Interface created: 2021-08-09 +superseded-by: --- # Algorand Wallet Algodv2 and Indexer API diff --git a/ARCs/arc-0010.md b/ARCs/arc-0010.md index 212612d02..b276d70d0 100644 --- a/ARCs/arc-0010.md +++ b/ARCs/arc-0010.md @@ -4,10 +4,11 @@ title: Algorand Wallet Reach Minimum Requirements description: Minimum requirements for Reach to function with a given wallet. author: DanBurton (@DanBurton) discussions-to: https://github.com/algorandfoundation/ARCs/issues/52 -status: Final +status: Deprecated type: Standards Track category: Interface created: 2021-08-09 +superseded-by: --- # Algorand Wallet Reach Minimum Requirements diff --git a/ARCs/arc-0011.md b/ARCs/arc-0011.md index 8401b1538..fc14fcb0a 100644 --- a/ARCs/arc-0011.md +++ b/ARCs/arc-0011.md @@ -4,10 +4,11 @@ title: Algorand Wallet Reach Browser Spec description: Convention for DApps to discover Algorand wallets in browser author: DanBurton (@DanBurton) discussions-to: https://github.com/algorandfoundation/ARCs/issues/52 -status: Final +status: Deprecated type: Standards Track category: Interface created: 2021-08-09 +superseded-by: --- # Algorand Wallet Reach Browser Spec diff --git a/ARCs/arc-0012.md b/ARCs/arc-0012.md index 370deda26..751ae42d6 100644 --- a/ARCs/arc-0012.md +++ b/ARCs/arc-0012.md @@ -1,7 +1,7 @@ --- arc: 12 title: Claimable ASA from vault application -description: A smart signature contract account that can receive & disburse claimable Algorand Smart Assets (ASA) to an intended receipient account. +description: A smart signature contract account that can receive & disburse claimable Algorand Smart Assets (ASA) to an intended recipient account. author: Brian Whippo (@silentrhetoric), Joe Polny (@joe-p) discussions-to: https://github.com/algorandfoundation/ARCs/issues/131 status: Withdrawn @@ -11,13 +11,13 @@ created: 2022-09-05 withdrawal-reason: Not used, will be replaced by ARC-59 --- -# Claimable Algorand Standard Assets (ASAs) from vault application +# Claimable Algorand Standard Assets (ASAs) from vault application ## Abstract -The goal of this standard is to establish a standard in the Algorand ecosytem by which ASAs can be sent to an intended receiver even if their account is not opted in to the ASA. +The goal of this standard is to establish a standard in the Algorand ecosytem by which ASAs can be sent to an intended receiver even if their account is not opted in to the ASA. -A on-chain application, called a vault, will be used to custody assets on behalf of a given user, with only that user being able to withdraw assets. A master application will use box storage to keep track of the vault for any given Algorand account. +A on-chain application, called a vault, will be used to custody assets on behalf of a given user, with only that user being able to withdraw assets. A master application will use box storage to keep track of the vault for any given Algorand account. If integrated into ecosystem technologies including wallets, epxlorers, and dApps, this standard can provide enhanced capabilities around ASAs which are otherwise strictly bound at the protocol level to require opting in to be received. This also enables the ability to "burn" ASAs by sending them to the vault associated with the global Zero Address. @@ -28,7 +28,7 @@ Algorand requires accounts to opt in to receive any ASA, a fact which simultaneo 1. Grants account holders fine-grained control over their holdings by allowing them to select which assets to allow and preventing receipt of unwanted tokens. 2. Frustrates users and developers when accounting for this requirement especially since other blockchains do not have this requirement. -This ARC lays out a new way to navigate the ASA opt in requirement. +This ARC lays out a new way to navigate the ASA opt in requirement. ### Contemplated Use Cases @@ -36,7 +36,7 @@ The following use cases help explain how this capability can enhance the possibi #### Airdrops -An ASA creator who wants to send their asset to a set of accounts faces the challenge of needing their intended receivers to opt in to the ASA ahead of time, which requires non-trivial communication efforts and precludes the possibility of completing the airdrop as a surprise. This claimable ASA standard creates the ability to send an airdrop out to individual addresses so that the receivers can opt in and claim the asset at their convenience--or not, if they so choose. +An ASA creator who wants to send their asset to a set of accounts faces the challenge of needing their intended receivers to opt in to the ASA ahead of time, which requires non-trivial communication efforts and precludes the possibility of completing the airdrop as a surprise. This claimable ASA standard creates the ability to send an airdrop out to individual addresses so that the receivers can opt in and claim the asset at their convenience--or not, if they so choose. #### Reducing New User On-boarding Friction @@ -55,9 +55,9 @@ The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL ### Definitions -- **Claimable ASA**: An Algorand Standard Asset (ASA) which has been transferred to a vault following the standard set forth in this proposal such that only the intended receiver account can claim it at their convenience. +- **Claimable ASA**: An Algorand Standard Asset (ASA) which has been transferred to a vault following the standard set forth in this proposal such that only the intended receiver account can claim it at their convenience. - **Vaultt**: An Algorand application used to hold claimable ASAs for a given account. -- **Master**: An Algorand application used to keep track of all of the vaults created for Algorand accounts. +- **Master**: An Algorand application used to keep track of all of the vaults created for Algorand accounts. - **dApp**: A decentralized application frontend, interpreted here to mean an off-chain frontend (a webapp, native app, etc.) that interacts with applications on the blockchain. - **Explorer**: An off-chain application that allows browsing the blockchain, showing details of transactions. - **Wallet**: An off-chain application that stores secret keys for on-chain accounts and can display and sign transactions for these accounts. @@ -90,7 +90,7 @@ There are two smart contracts being utilized: The [vault](../assets/arc-0012/vau ###### Claim * Transfers ASA from vault to “receiver” -* Deletes box: ASA -> “funder” +* Deletes box: ASA -> “funder” * Returns ASA and box MBR to “funder” ###### Reject @@ -135,7 +135,7 @@ There are two smart contracts being utilized: The [vault](../assets/arc-0012/vau ## Rationale -This design was created to offer a standard mechanism by which wallets, explorers, and dapps could enable users to send, receive, and find claimable ASAs without requiring any changes to the core protocol. +This design was created to offer a standard mechanism by which wallets, explorers, and dapps could enable users to send, receive, and find claimable ASAs without requiring any changes to the core protocol. ## Backwards Compatibility @@ -151,7 +151,7 @@ This ARC makes no changes to the consensus protocol and creates no backwards com ## Security Considerations -Both applications (The vault and the master have been audited by TBD +Both applications (The vault and the master have not been audited) ## Copyright diff --git a/ARCs/arc-0015.md b/ARCs/arc-0015.md index e77423664..dbbf51c0e 100644 --- a/ARCs/arc-0015.md +++ b/ARCs/arc-0015.md @@ -4,14 +4,15 @@ title: Encrypted Short Messages description: Scheme for encryption/decryption that allows for private messages. author: Stéphane Barroso (@sudoweezy), Paweł Pierścionek (@urtho) discussions-to: https://github.com/algorandfoundation/ARCs/issues/* -status: Final +status: Deprecated type: Standards Track category: Interface created: 2022-11-21 requires: 4 +superseded-by: --- -# Encrypted Short Messages +# Encrypted Short Messages ## Abstract @@ -26,13 +27,13 @@ The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL To receive a message, an Account **MUST** create an application that follows this convention: -- A Local State named `public_key` **MUST** contain an *NACL Public Key (Curve 25519)* key +- A Local State named `public_key` **MUST** contain an *NACL Public Key (Curve 25519)* key - A Local State named `arc` **MUST** contain the value `arc15-nacl-curve25519` - A Box `inbox` where: - Keys is an ABI encoded of the tuple `(address,uint64)` containing the address of the sender and the round when the message is sent - - Value is an encoded **text** + - Value is an encoded **text** > With this design, for each round, the sender can only write one message per round. > For the same round, an account can receive multiple messages if distinct sender sends them @@ -55,7 +56,7 @@ The associated smart contract **MUST** implement the following ABI interface: }, { "name": "authorize", - "desc": "Authorize an addresse to send a message", + "desc": "Authorize an addresses to send a message", "args": [ { "type": "byte[]", "name": "address_to_add", "desc": "Address of a sender" }, { "type": "byte[]", "name": "info", "desc": "information about the sender" } @@ -82,12 +83,12 @@ The associated smart contract **MUST** implement the following ABI interface: ] } ``` -> Warning: The remove method only removes the box used for a message, but it is still possible to access it by looking at the indexer. +> Warning: The remove method only removes the box used for a message, but it is still possible to access it by looking at the indexer. ## Rationale -Algorand blockchain unlocks many new use cases - anonymous user login to dApps and classical WEB2.0 solutions being one of them. For many use-cases, anonymous users still require asynchronous event notifications, and email seems to be the only standard option at the time of the creation of this ARC. With wallet adoption of this standard, users will enjoy real-time encrypted A2P (application-to-person) notifications without having to provide their email addresses and without any vendor lock-in. +Algorand blockchain unlocks many new use cases - anonymous user login to dApps and classical WEB2.0 solutions being one of them. For many use-cases, anonymous users still require asynchronous event notifications, and email seems to be the only standard option at the time of the creation of this ARC. With wallet adoption of this standard, users will enjoy real-time encrypted A2P (application-to-person) notifications without having to provide their email addresses and without any vendor lock-in. -There is also a possibility to do a similar version of this ARC with one App which will store every message for every Account. +There is also a possibility to do a similar version of this ARC with one App which will store every message for every Account. Another approach was to use the note field for messages, but with box storage available, it was a more practical and secure design. @@ -96,7 +97,7 @@ Another approach was to use the note field for messages, but with box storage av The following codes are not audited and are only here for information purposes. It **MUST** not be used in production. -Here is an example of how the code can be run in python : +Here is an example of how the code can be run in python : [main.py](../assets/arc-0015/main.py). > The delete method is only for test purposes, it is not part of the ABI for an `ARC-15` Application. @@ -105,7 +106,7 @@ An example the application created using Beaker can be found here : ## Security Considerations -Even if the message is encrypted, it will stay on the blockchain. +Even if the message is encrypted, it will stay on the blockchain. If the secret key used to decrypt is compromised at one point, every related message IS at risk. ## Copyright diff --git a/ARCs/arc-0016.md b/ARCs/arc-0016.md index 15c19aad2..bf0b213e9 100644 --- a/ARCs/arc-0016.md +++ b/ARCs/arc-0016.md @@ -7,6 +7,7 @@ discussions-to: https://github.com/algorandfoundation/ARCs/issues/62 status: Final type: Standards Track category: ARC +sub-category: Asa created: 2022-01-04 --- diff --git a/ARCs/arc-0018.md b/ARCs/arc-0018.md index e287420c7..bc8048720 100644 --- a/ARCs/arc-0018.md +++ b/ARCs/arc-0018.md @@ -7,6 +7,7 @@ discussions-to: https://github.com/algorandfoundation/ARCs/issues/108 status: Final type: Standards Track category: Interface +sub-category: Application created: 2022-02-16 requires: 4, 20, 22 --- @@ -25,16 +26,16 @@ An example may include some music rights where the label, the artist, and any in ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 822.. -[Royalty Policy](#royalty-policy) - The name for the settings that define how royalty payments are collected. +[Royalty Policy](#royalty-policy) - The name for the settings that define how royalty payments are collected. [Royalty Enforcer](#royalty-enforcer) - The application that enforces the royalty payments given the Royalty Policy and performs transfers of the assets. -[Royalty Enforcer Administrator](#royalty-enforcer-administrator) - The account that may call administrative level methods against the Royalty Enforcer. -[Royalty Receiver](#royalty-receiver) - The account that receives the royalty payment. It can be any valid Algorand account. +[Royalty Enforcer Administrator](#royalty-enforcer-administrator) - The account that may call administrative level methods against the Royalty Enforcer. +[Royalty Receiver](#royalty-receiver) - The account that receives the royalty payment. It can be any valid Algorand account. [Royalty Basis](#royalty-basis) - The share of a payment that is due to the Royalty Receiver -[Royalty Asset](#royalty-asset) - The ASA that should have royalties enforced during a transfer. +[Royalty Asset](#royalty-asset) - The ASA that should have royalties enforced during a transfer. [Asset Offer](#asset-offer) - A data structure stored in local state for the current owner representing the number of units of the asset being offered and the authorizing account for any transfer requests. [Third Party Marketplace](#third-party-marketplace) - A third party marketplace may be any marketplace that implements the appropriate methods to initiate transfers. -### Royalty Policy +### Royalty Policy ```ts interface RoyaltyPolicy { @@ -42,61 +43,61 @@ interface RoyaltyPolicy { royalty_recipient: string // The address that should collect the payment } ``` -A Royalty Share consists of a `royalty_receiver` that should receive a Royalty payment and a `royalty_basis` representing some share of the total payment amount. +A Royalty Share consists of a `royalty_receiver` that should receive a Royalty payment and a `royalty_basis` representing some share of the total payment amount. ### Royalty Enforcer -The Royalty Enforcer is an instance of the contract, an Application, that controls the transfer of ASAs subject to the Royalty Policy. +The Royalty Enforcer is an instance of the contract, an Application, that controls the transfer of ASAs subject to the Royalty Policy. This is accomplished by exposing an interface defined as a set of [ABI Methods](#abi-methods) allowing a grouped transaction call containing a payment and a [Transfer](#transfer) request. ### Royalty Enforcer Administrator -The Royalty Enforcer Administrator is the account that has privileges to call administrative actions against the Royalty Enforcer. If one is not set the account that created the application MUST be used. +The Royalty Enforcer Administrator is the account that has privileges to call administrative actions against the Royalty Enforcer. If one is not set the account that created the application MUST be used. To update the Royalty Enforcer Administrator the [Set Administrator](#set-administrator) method is called by the current administrator and passed the address of the new administrator. An implementation of this spec may choose how they wish to enforce a that method is called by the administrator. ### Royalty Receiver -The Royalty Receiver is a generic account that could be set to a Single Signature, a Multi Signature, a Smart Signature or even to another Smart Contract. +The Royalty Receiver is a generic account that could be set to a Single Signature, a Multi Signature, a Smart Signature or even to another Smart Contract. The Royalty Receiver is then responsible for any further royalty distribution logic, making the Royalty Enforcement Specification more general and composable. -### Royalty Basis +### Royalty Basis -The Royalty Basis is value representing the percentage of the payment made during a transfer that is due to the Royalty Receiver. +The Royalty Basis is value representing the percentage of the payment made during a transfer that is due to the Royalty Receiver. The Royalty Basis **MUST** be specified in terms of basis points https://en.wikipedia.org/wiki/Basis_point of the payment amount. -### Royalty Asset +### Royalty Asset -The Royalty Asset is an ASA subject to royalty payment collection and **MUST** be created with the [appropriate parameters](#royalty-asset-parameters). -> Because the protocol does not allow updating an address parameter after it's been deleted, +The Royalty Asset is an ASA subject to royalty payment collection and **MUST** be created with the [appropriate parameters](#royalty-asset-parameters). +> Because the protocol does not allow updating an address parameter after it's been deleted, > if the asset creator thinks they may want to modify them later, they must be set to some non-zero address. #### Asset Offer -The Asset Offer is the a data structure stored in the owner's local state. It is keyed in local storage by the byte string representing the ASA Id. +The Asset Offer is the a data structure stored in the owner's local state. It is keyed in local storage by the byte string representing the ASA Id. ```ts interface AssetOffer { auth_address: string // The address of a marketplace or account that may issue a transfer request offered_amount: number // The number of units being offered } ``` -This concept is important to this specification because we use the clawback feature to transfer the assets. Without some signal that the current owner is willing to have their assets transferred, it may be possible to transfer the asset without their permission. +This concept is important to this specification because we use the clawback feature to transfer the assets. Without some signal that the current owner is willing to have their assets transferred, it may be possible to transfer the asset without their permission. In order for a transfer to occur, this field **MUST** be set and the parameters of the transfer request **MUST** match the value set. -> A transfer matching the offer would require the transfer amount <= offered amount and that the transfer is sent by auth_address. +> A transfer matching the offer would require the transfer amount <= offered amount and that the transfer is sent by auth_address. After the transfer is completed this value **MUST** be wiped from the local state of the owner's account. #### Royalty Asset Parameters The Clawback parameter **MUST** be set to the Application Address of the Royalty Enforcer. -> Since the Royalty Enforcer relies on using the Clawback mechanism to perform the transfer the Clawback should NEVER be set to the zero address. +> Since the Royalty Enforcer relies on using the Clawback mechanism to perform the transfer the Clawback should NEVER be set to the zero address. The Freeze parameter **MUST** be set to the Application Address of the Royalty Enforcer if `FreezeAddr != ZeroAddress`, else set to `ZeroAddress`. -> If the asset creator wants to allow an ASA to be Royalty Free after some conditions are met, it should be set to the Application Address +> If the asset creator wants to allow an ASA to be Royalty Free after some conditions are met, it should be set to the Application Address The Manager parameter **MUST** be set to the Application Address of the Royalty Enforcer if `ManagerAddr != ZeroAddress`, else set to `ZeroAddress`. > If the asset creator wants to update the Freeze parameter, this should be set to the application address The Reserve parameter **MAY** be set to anything. The `DefaultFrozen` **MUST** be set to true. ### Third Party Marketplace -In order to support secondary sales on external markets this spec was designed such that the Royalty Asset may be listed without transferring it from the current owner's account. +In order to support secondary sales on external markets this spec was designed such that the Royalty Asset may be listed without transferring it from the current owner's account. A Marketplace may call the transfer request as long as the address initiating the transfer has been set as the `auth_address` through the [offer](#offer) method in some previous transaction by the current owner. ### ABI Methods @@ -118,15 +119,15 @@ The `administrator` parameter is the address of the account that should be set a #### Set Policy: *REQUIRED* - + ``` set_policy( - royalty_basis: uint64, + royalty_basis: uint64, royalty_recipient: account, ) ``` Sets the policy for any assets using this application as a Royalty Enforcer. -The `royalty_basis` is the percentage for royalty payment collection, specified in basis points (e.g., 1% is 100). +The `royalty_basis` is the percentage for royalty payment collection, specified in basis points (e.g., 1% is 100). A Royalty Basis **SHOULD** be immutable, if an application call is made that would overwrite an existing value it **SHOULD** fail. See [Security Considerations](#security-considerations) for more details on how to handle this parameters mutability. The `royalty_receiver` is the address of the account that should receive a partial share of the payment for any [transfer](#transfer) of an asset subject to royalty collection. @@ -135,39 +136,39 @@ The `royalty_receiver` is the address of the account that should receive a parti *REQUIRED* ``` set_payment_asset( - payment_asset: asset, + payment_asset: asset, allowed: boolean, ) ``` The `payment_asset` argument represents the ASA id that is acceptable for payment. The contract logic **MUST** opt into the asset specified in order to accept them as payment as part of a transfer. This method **SHOULD** have checks to ensure it is being called by the current administrator. The `allowed` argument is a boolean representing whether or not this asset is allowed. -The Royalty Receiver **MUST** be opted into the full set of assets contained in this list of payment_assets. +The Royalty Receiver **MUST** be opted into the full set of assets contained in this list of payment_assets. > In the case that an account is not opted into an asset, any transfers where payment is specified for that asset will fail until the account opts into the asset. or the policy is updated. -#### Transfer: +#### Transfer: *REQUIRED* ``` transfer_algo_payment( - royalty_asset: asset, - royalty_asset_amount: uint64, - from: account, - to: account, - royalty_receiver: account, - payment: pay, + royalty_asset: asset, + royalty_asset_amount: uint64, + from: account, + to: account, + royalty_receiver: account, + payment: pay, current_offer_amount: uint64, ) ``` And ``` transfer_asset_payment( - royalty_asset: asset, - royalty_asset_amount: uint64, - from: account, - to: account, - royalty_receiver: account, - payment: axfer, - payment_asset: asset, + royalty_asset: asset, + royalty_asset_amount: uint64, + from: account, + to: account, + royalty_receiver: account, + payment: axfer, + payment_asset: asset, current_offer_amount: uint64, ) ``` @@ -175,17 +176,17 @@ Transfers the Asset after checking that the royalty policy is adhered to. This c There **MUST** be a royalty policy defined prior to attempting a transfer. There are two different method signatures specified, one for simple Algo payments and one for Asset as payment. The appropriate method should be called depending on the circumstance. -The `royalty_asset` is the ASA ID to be transferred. +The `royalty_asset` is the ASA ID to be transferred. The `from` parameter is the account the ASA is transferred from. The `to` parameter is the account the ASA is transferred to. -The `royalty_receiver` parameter is the account that collects the royalty payment. +The `royalty_receiver` parameter is the account that collects the royalty payment. The `royalty_asset_amount` parameter is the number of units of this ASA ID to transfer. The amount **MUST** be less than or equal to the amount [offered](#offer) by the `from` account. -The `payment` parameter is a reference to the transaction that is transferring some asset (ASA or Algos) from the buyer to the Application Address of the Royalty Enforcer. -The `payment_asset` parameter is specified in the case that the payment is being made with some ASA rather than with Algos. It **MUST** match the Asset ID of the AssetTransfer payment transaction. -The `current_offer_amount` parameter is the current amount of the Royalty Asset [offered](#offer) by the `from` account. +The `payment` parameter is a reference to the transaction that is transferring some asset (ASA or Algos) from the buyer to the Application Address of the Royalty Enforcer. +The `payment_asset` parameter is specified in the case that the payment is being made with some ASA rather than with Algos. It **MUST** match the Asset ID of the AssetTransfer payment transaction. +The `current_offer_amount` parameter is the current amount of the Royalty Asset [offered](#offer) by the `from` account. The transfer call **SHOULD** be part of a group with a size of 2 (payment/asset transfer + app call) > See [Security Considerations](#security-considerations) for details on how this check may be circumvented. -Prior to each transfer the Royalty Enforcer **SHOULD** assert that the Seller (the `from` parameter) and the Buyer (the `to` parameter) have blank or unset `AuthAddr`. +Prior to each transfer the Royalty Enforcer **SHOULD** assert that the Seller (the `from` parameter) and the Buyer (the `to` parameter) have blank or unset `AuthAddr`. > This reasoning for this check is described in [Security Considerations](#security-considerations). It is purposely left to the implementor to decide if it should be checked. #### Offer: @@ -193,27 +194,27 @@ Prior to each transfer the Royalty Enforcer **SHOULD** assert that the Seller (t *REQUIRED* ``` offer( - royalty_asset: asset, - royalty_asset_amount: uint64, - auth_address: account, - offered_amount: uint64, + royalty_asset: asset, + royalty_asset_amount: uint64, + auth_address: account, + offered_amount: uint64, offered_auth_addr: account, ) ``` Flags the asset as transferrable and sets the address that may initiate the transfer request. -The `royalty_asset` is the ASA ID that is being offered. -The `royalty_asset_amount` is the number of units of the ASA ID that are offered. The account making this call **MUST** have at least this amount. -The `auth_address` is the address that may initiate a [transfer](#transfer). +The `royalty_asset` is the ASA ID that is being offered. +The `royalty_asset_amount` is the number of units of the ASA ID that are offered. The account making this call **MUST** have at least this amount. +The `auth_address` is the address that may initiate a [transfer](#transfer). > This address may be any valid address in the Algorand network including an Application Account's address. The `offered_amount` is the number of units of the ASA ID that are currently offered. > In the case that this is an update, it should be the amount being replaced. In the case that this is a new offer it should be 0. The `offered_auth_address` is the address that may currently initiate a [transfer](#transfer). > In the case that this is an update, it should be the address being replaced. In the case that this is a new offer it should be the zero address. If any transfer is initiated by an address that is _not_ listed as the `auth_address` for this asset ID from this account, the transfer **MUST** be rejected. -If this method is called when there is an existing entry for the same `royalty_asset`, the call is treated as an update. In the case of an update case the contract **MUST** compare the `offered_amount` and `offered_auth_addr` with what is currently set. If the values differ, the call **MUST** be rejected. +If this method is called when there is an existing entry for the same `royalty_asset`, the call is treated as an update. In the case of an update case the contract **MUST** compare the `offered_amount` and `offered_auth_addr` with what is currently set. If the values differ, the call **MUST** be rejected. > This requirement is meant to prevent a sort of race condition where the `auth_address` has a `transfer` accepted before the `offer`-ing account sees the update. In that case the offering account might try to offer more than they would otherwise want to. An example is offered in [security considerations](#security-considerations) To rescind an offer, this method is called with 0 as the new offered amount. -If a [transfer](#transfer) or [royalty_free_move](#royalty-free-move) is called successfully, the `offer` **SHOULD** be updated or deleted from local state. +If a [transfer](#transfer) or [royalty_free_move](#royalty-free-move) is called successfully, the `offer` **SHOULD** be updated or deleted from local state. > Exactly how to update the offer is left to the implementer. In the case of a partially filled offer, the amount may be updated to reflect some new amount that represents `offered_amount - amount transferred` or the offer may be deleted completely. #### Royalty Free Move: @@ -221,21 +222,21 @@ If a [transfer](#transfer) or [royalty_free_move](#royalty-free-move) is called *OPTIONAL* ``` royalty_free_move( - royalty_asset: asset, - royalty_asset_amount: uint64, + royalty_asset: asset, + royalty_asset_amount: uint64, from: account, - to: account, + to: account, offered_amount: uint64, ) ``` -Moves an asset to the new address without collecting any royalty payment. +Moves an asset to the new address without collecting any royalty payment. Prior to this method being called the current owner **MUST** offer their asset to be moved. The `auth_address` of the offer **SHOULD** be set to the address of the Royalty Enforcer Administrator and calling this method **SHOULD** have checks to ensure it is being called by the current administrator. > This May be useful in the case of a marketplace where the NFT must be placed in some escrow account. Any logic may be used to validate this is an authorized transfer. The `royalty_asset` is the asset being transferred without applying the Royalty Enforcement logic. The `royalty_asset_amount` is the number of units of this ASA ID that should be moved. The `from` parameter is the current owner of the asset. The `to` parameter is the intended receiver of the asset. -The `offered_amount` is the number of units of this asset currently offered. This value **MUST** be greater than or equal to the amount being transferred. +The `offered_amount` is the number of units of this asset currently offered. This value **MUST** be greater than or equal to the amount being transferred. > The `offered_amount` value for is passed to prevent the race or attack described in [Security Considerations](#security-considerations). ### Read Only Methods Three methods are specified here as `read-only` as defined in [ARC-22](./arc-0022.md). @@ -254,14 +255,14 @@ The return value is a tuple of type `(address,uint64)`, where the `address` is t *REQUIRED* ``` get_offer( - royalty_asset: asset, + royalty_asset: asset, from: account, )(address,uint64) ``` Gets the current [Asset Offer](#asset-offer) for a given asset as set by its owner. The `royalty_asset` parameter is the asset id of the [Royalty Asset](#royalty-asset) that has been offered The `from` parameter is the account that placed the offer -The return value is a tuple of type `(address,uint64)`, where `address` is the authorizing address that may make a transfer request and the `uint64` it the amount offered. +The return value is a tuple of type `(address,uint64)`, where `address` is the authorizing address that may make a transfer request and the `uint64` it the amount offered. #### Get Administrator: @@ -270,7 +271,7 @@ The return value is a tuple of type `(address,uint64)`, where `address` is the a get_administrator()address ``` Gets the [Royalty Enforcer Administrator](#royalty-enforcer-administrator) set for this Royalty Enforcer. -The return value is of type `address` and represents the address of the account that may call administrative methods for this Royalty Enforcer application +The return value is of type `address` and represents the address of the account that may call administrative methods for this Royalty Enforcer application ### Storage @@ -278,7 +279,7 @@ While the details of storage are described here, `readonly` methods are specifie #### Global Storage -The parameters that describe a policy are stored in Global State. +The parameters that describe a policy are stored in Global State. The relevant keys are: `royalty_basis` - The percentage specified in basis points of the payment `royalty_receiver` - The account that should be paid the royalty @@ -287,7 +288,7 @@ Another key is used to store the current administrator account: #### Local Storage -For an offered Asset, the authorizing address and amount offered should be stored in a Local State field for the account offering the Asset. +For an offered Asset, the authorizing address and amount offered should be stored in a Local State field for the account offering the Asset. ### Full ABI Spec @@ -527,8 +528,8 @@ Let Carol be a buyer of a Royalty Asset ``` ```mermaid sequenceDiagram - Alice->>Royalty Enforcer: set_policy with Royalty Basis and Royalty Receiver - Alice->>Royalty Enforcer: set_payment_asset with any asset that should be accepted as payment + Alice->>Royalty Enforcer: set_policy with Royalty Basis and Royalty Receiver + Alice->>Royalty Enforcer: set_payment_asset with any asset that should be accepted as payment par List Bob->>Royalty Enforcer: offer Bob->>Marketplace: list @@ -540,7 +541,7 @@ sequenceDiagram Royalty Enforcer->>Alice: royalty payment end par Delist - Bob->>Royalty Enforcer: offer 0 + Bob->>Royalty Enforcer: offer 0 Bob->>Marketplace: delist end ``` @@ -548,8 +549,8 @@ sequenceDiagram ### Metadata The metadata associated to an asset **SHOULD** conform to any ARC that supports an additional field in the `properties` section specifying the specific information relevant for off-chain applications like wallets or Marketplace dApps. The metadata **MUST** be immutable. -The fields that should be specified are the `application-id` as described in [ARC-20](./arc-0020.md) and `rekey-checked` which describes whether or not this application implements the rekey checks during transfers. -Example: +The fields that should be specified are the `application-id` as described in [ARC-20](./arc-0020.md) and `rekey-checked` which describes whether or not this application implements the rekey checks during transfers. +Example: ```js //... "properties":{ @@ -580,14 +581,14 @@ https://github.com/algorand-devrel/royalty ## Security Considerations -There are a number of security considerations that implementers and users should be aware of. +There are a number of security considerations that implementers and users should be aware of. *Royalty policy mutability* -The immutability of a royalty basis is important to consider since mutability introduces the possibility for a situation where, after an initial sale, the royalty policy is updated from 1% to 100% for example. This would make any further sales have the full payment amount sent to the royalty recipient and the seller would receive nothing. This specification is written with the recommendation that the royalty policy **SHOULD** be immutable. This is not a **MUST** so that an implementation may decrease the royalty basis may decrease over time. -Caution should be taken by users and implementers when evaluating how to implement the exact logic. +The immutability of a royalty basis is important to consider since mutability introduces the possibility for a situation where, after an initial sale, the royalty policy is updated from 1% to 100% for example. This would make any further sales have the full payment amount sent to the royalty recipient and the seller would receive nothing. This specification is written with the recommendation that the royalty policy **SHOULD** be immutable. This is not a **MUST** so that an implementation may decrease the royalty basis may decrease over time. +Caution should be taken by users and implementers when evaluating how to implement the exact logic. *Spoofed payment* -While its possible to enforce the group size limit, it is possible to circumvent the royalty enforcement logic by simply making an Inner Transaction application call with the appropriate parameters and a small payment, then in the same outer group the "real" payment. The counter-party risk remains the same since the inner transaction is atomic with the outers. -In addition, it is always possible to circumvent the royalty enforcement logic by using an escrow account in the middle: - - Alice wants to sell asset A to Bob for 1M USDC. +While its possible to enforce the group size limit, it is possible to circumvent the royalty enforcement logic by simply making an Inner Transaction application call with the appropriate parameters and a small payment, then in the same outer group the "real" payment. The counter-party risk remains the same since the inner transaction is atomic with the outers. +In addition, it is always possible to circumvent the royalty enforcement logic by using an escrow account in the middle: + - Alice wants to sell asset A to Bob for 1M USDC. - Alice and Bob creates an escrow ESCROW (smart signature). - Alice sends A for 1 μAlgo to the ESCROW - Bob sends 1M USDC to ESCROW. @@ -597,7 +598,7 @@ The exact logic that should determine _if_ a transfer should be allowed is left *Rekey to swap* Rekeying an account can also be seen as circumventing this logic since there is no counter-party risk given that a rekey can be grouped with a payment. We address this by suggesting the `auth_addr` on the buyer and seller accounts are both set to the zero address. *Offer for unintended clawback* -Because we use the clawback mechanism to move the asset, we need to be sure that the current owner is actually interested in making the sale. We address this by requiring the [offer](#offer) method is called to set an authorized address OR that the AssetSender is the one making the application call. +Because we use the clawback mechanism to move the asset, we need to be sure that the current owner is actually interested in making the sale. We address this by requiring the [offer](#offer) method is called to set an authorized address OR that the AssetSender is the one making the application call. *Offer double spend* If the [offer](#offer) method did not require the current value be passed, a possible attack or race condition may be taken advantage of. - There's an open offer for N. @@ -605,9 +606,9 @@ If the [offer](#offer) method did not require the current value be passed, a pos - I see that; decide to "frontrun" the second tx and first get N, [here the ledger should apply the change of offer, which overwrites the previous value — now 0 — with M], then I can get another M of the asset. *Mutable asset parameters* If the ASA has it's manager parameter set, it is possible to change the other address parameters. Namely the clawback and freeze roles could be changed to allow an address that is _not_ the Royalty Enforcer's application address. For that reason the manager **MUST** be set to the zero address or to the Royalty Enforcer's address. -*Compatability of existing ASAs* +*Compatibility of existing ASAs* In the case of [ARC-69](./arc-0069.md) and [ARC-19](./arc-0019.md) ASA's the manager is the account that may issue `acfg` transactions to update metadata or to change the reserve address. For the purposes of this spec the manager **MUST** be the application address, so the logic to issue appropriate `acfg` transactions should be included in the application logic if there is a need to update them. -> When evaluating whether or not an existing ASA may be compatible with this spec, note that the `clawback` address needs to be set to the application address of the Royalty Enforcer. The `freeze` address and `manager` address may be empty or, if set, must be the application address. If these addresses aren't set correctly, the royalty enforcer will not be able to issue the transactions required and there may be security considerations. +> When evaluating whether or not an existing ASA may be compatible with this spec, note that the `clawback` address needs to be set to the application address of the Royalty Enforcer. The `freeze` address and `manager` address may be empty or, if set, must be the application address. If these addresses aren't set correctly, the royalty enforcer will not be able to issue the transactions required and there may be security considerations. > The `reserve` address has no requirements in this spec so [ARC-19](./arc-0019.md) ASAs should have no issue assuming the rest of the addresses are set correctly. ## Copyright diff --git a/ARCs/arc-0019.md b/ARCs/arc-0019.md index bce36a324..2d8db1d06 100644 --- a/ARCs/arc-0019.md +++ b/ARCs/arc-0019.md @@ -7,18 +7,19 @@ discussions-to: https://github.com/algorandfoundation/ARCs/issues/73 status: Final type: Standards Track category: ARC +sub-category: Asa created: 2021-01-23 --- ## Abstract This ARC describes a template substitution for URLs in ASAs, initially for ipfs:// scheme URLs allowing mutable CID replacement in rendered URLs. -The proposed template-XXX scheme has substitions like: +The proposed template-XXX scheme has substitutions like: ``` template-ipfs://{ipfscid::::}[/...] ``` -This will allow modifying the 32-byte 'Reserve address' in an ASA to represent a new IPFS content-id hash. Changing of the reserve address via an asset-config transaction will be all that is needed to point an ASA URL to new IPFS content. The client reading this URL, will compose a fully formed IPFS Content-ID based on the version, multicodec, and hash arguments provided in the ipfscid substitition. +This will allow modifying the 32-byte 'Reserve address' in an ASA to represent a new IPFS content-id hash. Changing of the reserve address via an asset-config transaction will be all that is needed to point an ASA URL to new IPFS content. The client reading this URL, will compose a fully formed IPFS Content-ID based on the version, multicodec, and hash arguments provided in the ipfscid substitution. ## Motivation @@ -30,15 +31,15 @@ Of the parameters that are mutable, the Reserve address is somewhat distinct in These 32-bytes can, for example, hold a SHA2-256 hash uniquely referencing the desired content for the ASA (ARC-3-like metadata for example) -Using the reserve address in this way means that what an ASA 'points to' for metadata can be changed with a single asset config transaction, changing only the 32-bytes of the reserve address. The new value is accessible via even non-archival nodes with a single call to the `/v2/assets/xxx` REST endpoint. +Using the reserve address in this way means that what an ASA 'points to' for metadata can be changed with a single asset config transaction, changing only the 32-bytes of the reserve address. The new value is accessible via even non-archival nodes with a single call to the `/v2/assets/xxx` REST endpoint. ## Specification The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in RFC-2119. -This proposal specifies a method to provide mutability for IPFS hosted content-ids. The intention is that FUTURE ARCs could define additional template substitutions, but this is not meant to be a kitchen sink of templates, only to establish a possible baseline of syntax. +This proposal specifies a method to provide mutability for IPFS hosted content-ids. The intention is that FUTURE ARCs could define additional template substitutions, but this is not meant to be a kitchen sink of templates, only to establish a possible baseline of syntax. -An indication that this ARC is in use is defined by an ASA URL's "scheme" having the prefix "**template-**". +An indication that this ARC is in use is defined by an ASA URL's "scheme" having the prefix "**template-**". An Asset conforming this specification **MUST** have: @@ -49,19 +50,19 @@ The URL of the asset must be of the form: template-ipfs://(...) ``` -> The ipfs:// scheme is already somewhat of a meta scheme in that clients interpret the ipfs scheme as referencing an IPFS CID (version 0/base58 or 1/base32 currently) followed by optional path within certain types of IPFS DAG content (IPLD CAR content for example). The clients take the CID and use to fetch directly from the IPFS network directly via IPFS nodes, or via various IPFS gateways (https://ipfs.io/ipfs/CID[/...], pinata, etc.)). +> The ipfs:// scheme is already somewhat of a meta scheme in that clients interpret the ipfs scheme as referencing an IPFS CID (version 0/base58 or 1/base32 currently) followed by optional path within certain types of IPFS DAG content (IPLD CAR content for example). The clients take the CID and use to fetch directly from the IPFS network directly via IPFS nodes, or via various IPFS gateways (https://ipfs.io/ipfs/CID[/...], pinata, etc.)). 2. **An "ipfscid" _template_ argument in place of the normal CID.** Where the format of templates are `{