CHIP-0019: Restricted CAT Standard

CHIPs/chip-0019.md

@@ -0,0 +1,127 @@
+CHIP Number   | 0019
+:-------------|:----
+Title         | Restricted CAT Standard
+Description   | A standard for implementing Restricted Chia Asset Tokens (CATs) on Chia's blockchain
+Author        | [Matt Hauff](https://github.com/Quexington)
+Editor        | [Dan Perry](https://github.com/danieljperry)
+Comments-URI  | [PR #68](https://github.com/Chia-Network/chips/pull/68)
+Status        | Stagnant
+Category      | Standards Track
+Sub-Category  | Chialisp
+Created       | 2023-04-25
+Requires      | [0016](https://github.com/Chia-Network/chips/pull/65), [CAT2](https://chialisp.com/cats)
+Replaces      | None
+Superseded-By | None
+
+## Abstract
+Restricted CATs are tokens on Chia's blockchain whose ownership is restricted to people or other entities who possess a required set of Verifiable Credentials (VCs).
+
+## Definitions
+Throughout this document, we'll use the following terms:
+* **Must, required, shall** – These words indicate an absolute requirement of the specification
+* **Must not, shall not** – These phrases indicate an absolute prohibition of the specification
+* **Should, recommended** – These words indicate something that is not a requirement of the specification, but the implications of not following it should be carefully considered beforehand
+* **Should not, not recommended** – These phrases indicate something that is not a prohibition of the specification, but the implications of following it should be carefully considered beforehand
+* **May** – This word indicates something that is optional. Interoperability between implementations must not be broken because of the choice to implement, or not to implement, this feature
+
+## Motivation
+
+The seller of an asset sometimes needs to restrict potential buyers to entities that meet certain qualifications. Some examples of assets with this requirement include financial instruments such as unregistered securities, convertible investments, real estate investment trusts, and fixed income securities, as well as non-financial instruments such as concert tickets, club memberships, and admissions to events. The qualifications required to buy such an asset might include being an accredited investor, being a non US resident or citizen, or having paid club membership dues.
+
+Restricted CATs are similar to standard Chia Asset Tokens (CATs), with the extra requirement that anyone who wants to acquire and/or trade them must fulfill certain qualifications in order to do so. An example of such a qualification is the possession of a Verifiable Credential that contains a set of proofs specific to that restricted CAT. Just like standard CATs, Restricted CATs can be traded peer-to-peer on a bulletin board by using Chia [Offers](https://chialisp.com/offers/).
+
+### Entities involved
+Restricted CATs involve the following four entities:
+
+1. Credential holder - the individual or entity who has been issued, and currently holds, the VC
+  * Note - The W3C specification defines a [subject](https://www.w3.org/TR/vc-data-model/#dfn-subjects) as `A thing about which claims are made.` The holder and the subject are typically, but not always, the same entity. This CHIP will refer to this entity as the `subject` before they hold the VC, and as the `holder` when they hold it
+2. Credential issuer - the entity that creates and signs the VC, thus asserting the claims about the holder's identity, attributes, or qualifications
+3. Verifier - the entity that verifies the authenticity and validity of the VC by checking the cryptographic signatures, trustworthiness of the issuer, and the relevance of the claims to the context of the transaction or interaction
+4. Security issuer - the entity that wishes to issue the Restricted CATs
+
+## Backwards Compatibility
+Restricted CATs are a Chialisp standard that extends the CAT2 standard, and does not replace any existing standards. If this CHIP is accepted, the CAT2 standard will continue to function without modification. This CHIP does not introduce any backward incompatibilities.
+
+## Rationale
+The design for Restricted CATs consists of three basic components:
+1. **CAT extension** – The required tokens closely resemble Chia Asset Tokens (CATs). Because the CAT2 standard is already in use today, it made sense to extend that standard rather than create a new one
+
+2. **Verification** – A proofs checker puzzle is used to perform verification of a holder's proofs, as detailed in the [Specification section](#specification). This verification is a required feature because it allows a security issuer to issue Restricted CATs only to certain people or other entities. For example, a security issuer could limit the issuance of their Restricted CAT to those who are:
+    * At least 18 years old
+    * Not a citizen or resident of the United States of America
+
+Additionally, the design for Restricted CATs includes the requirement that they must be compatible with Chia Offers. This requirement exists so that Restricted CATs may be traded peer-to-peer on bulletin boards.
+
+### Workflow
+
+This section presents a basic workflow for acquiring and using Chia Restricted CATs. The following roles will be used in this example:
+1. Credential subject/holder - the person who wishes to obtain a credential (the subject) or who is currently holding the credential (the holder)
+2. Credential issuer - the company that issues the credential
+3. Verifier and security issuer - the company that verifies the authenticity of the credential; also the company that issues Restricted CATs
+
+The following process will be used to obtain and use the Restricted CATs in this example:
+1. The subject goes through the necessary steps with the credential issuer to obtain a VC. The subject is now the holder of the VC
+2. The holder applies with the security issuer to receive an issuance of Restricted CATs
+3. The security issuer verifies the authenticity and current validity of the credential
+4. The security issuer issues the Restricted CATs to the holder
+5. The holder can now sell the Restricted CATs to any other holders of the same VC
+
+## Specification
+
+#### Restricted CAT Structure
+Restricted CATs extend the CAT2 standard by wrapping coins with the [credential restriction](https://github.com/Chia-Network/chia-blockchain/blob/main/chia/wallet/vc_wallet/cr_puzzles/credential_restriction.clsp) puzzle, which ensures that the coins will require the correct set of VCs in order to be spent. Whenever the coins are spent, they call a [proofs checker](https://github.com/Chia-Network/chia-blockchain/blob/main/chia/wallet/vc_wallet/cr_puzzles/flag_proofs_checker.clsp) puzzle, which checks any proofs that are revealed.
+
+Note that any type of Chia coin (CATs, NFTs, etc) could be wrapped with a Chialisp puzzle that restricts ownership based on credentials. However, the standard in this CHIP only supports wrapping CAT2 coins.
+
+#### Restricted CATs usage outline
+1. The security issuer mints the desired number of Restricted CATs, where:
+    * In order to be transferred, the Restricted CATs require that a VC with a set of matching proof(s) authorize it to make the transfer
+    * Without the matching proof(s), the Restricted CATs cannot be transferred
+2. The VC of the subject (receiver) who wishes to purchase the Restricted CATs creates an announcement, which the Restricted CATs then use to verify that the Merkle root in the VC contains the correct proofs
+3. The subject (receiver) uses the VC to authorize the transfer of the Restricted CATs
+4. The authorization adds to a chain of custody on the blockchain, i.e. a history of each token and which VC(s) have owned it, similar to NFT provenance
+5. The history will give the security issuer confidence that they know who has owned the Restricted CATs
+
+#### Proofs checker
+A default proofs checker is included in the Restricted CAT specification. This Chialisp puzzle looks for a list of `(key, value)` pairs, where:
+* The `key` is a flag, such as `over_18`, `us_citizen`, etc
+* The value is a boolean indicating whether the key has been met
+
+In order for the default proofs checker to succeed, each of the values is required to be `true`:
+* If the values are all `true`, the proofs checker will return `true`
+* If any of the values are `false` or missing, the proofs checker will return `false`
+
+A few notes about proofs checkers:
+* The default proofs checker requires `(key, value)` pairs, where the `key` is a string and the `value` is a boolean. This only pertains to the Chialisp puzzle and the on-chain representation of proofs
+* The off-chain metadata may use a different structure to represent the proofs. In order to be W3C conformant, the default VC Structure CHIP will use `(key, value)` pairs, where the `key` and `value` are both strings. This metadata will need to be converted into a structure that the default proofs checker will recognize when processing on-chain proofs
+* A different proofs checker with a different structure may also be used. For example, the flags could also include more complex logic, such as `over_18 OR signature_from_parent`
+
+#### Allowed modifications
+Some features outlined in this CHIP could be modified while still conforming to the specification:
+
+* **On-chain enforcement of VC possession**
+  * Ideally, in order for a public/private key pair to possess a Restricted CAT, the same key pair must also possess the required VC(s)
+  * However, by default, Restricted CATs simply require the correct VC to authorize their transfer. There is currently no requirement that the public/private key pair that possesses the VC is the only key pair that may receive a Restricted CAT. A VC could therefore authorize the transfer of a Restricted CAT to a different wallet
+  * Though the default behavior is not ideal, Restricted CATs will still build a list of VCs that have authorized their transfer. This will create a chain of custody, similar to NFT provenance. In other words, the current on-chain information will ensure auditability, but not enforcement
+
+* **Restricted CAT revocation**
+  * Ideally, when a user's VC is revoked, the issuer of the Restricted CATs that require the revoked VC would have the option to remove the Restricted CATs from the user's wallet
+  * However, by default, the user will continue to hold the Restricted CATs, even after their VC has been revoked. At this point, the user can transfer the Restricted CATs to someone else who holds the appropriate VC. This does mean that in order to purchase Restricted CATs from someone other than the security issuer, a user must trust that the seller was allowed to possess the Restricted CATs being sold
+
+* **Proofs checker**
+  * As stated above, the default proofs checker could be replaced with a custom Chialisp puzzle
+
+## Test Cases
+Test cases will be posted here prior to this CHIP's completion.
+
+## Reference Implementation
+The reference implementation for Restricted CATs is located on GitHub, in the [/chia/wallet/vc_wallet](https://github.com/Chia-Network/chia-blockchain/tree/main/chia/wallet/vc_wallet) folder of the `chia-blockchain` repository.
+
+## Security
+There currently are plans to conduct a security audit of the source code from this CHIP.
+
+## Additional Assets
+* [Credential Restriction Puzzle](/assets/chip-0019/credential_restriction_puzzle.png) diagram
+
+## Copyright
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).