Add coinid operator and new softfork info

CHIPs/chip-0011.md

@@ -15,7 +15,7 @@ Superseded-By | None
 
 ## Abstract
 
-This CHIP will add a set of new operators to the CLVM. These operators will enable complex BLS operations, as well as new functionality such as ZK proofs.
+This CHIP will add a set of new operators to the CLVM. These operators will enable complex BLS operations, as well as new functionality such as ZK proofs, and the ability to calculate a coin ID from its component parts. Initially, the operators will be accessible from behind the `softfork` guard. Later, they will become part of the core CLVM.
 
 ## Definitions
 
@@ -34,18 +34,24 @@ CLVM currently includes a BLS operator called [point_add](https://chialisp.com/o
 
 This CHIP will add a new set of operators to CLVM in order to utilize the full capabilities of BLS signatures. For example, the new operators will add the ability to verify signatures and to use ZK proofs.
 
+In addition, CLVM currently lacks a way to calculate a coin ID, and to validate its components. To solve this, a new operator will be added to the CLVM that calculates a coin ID from its parent coin ID, puzzle-hash, and amount. The operator will fail if any of the arguments are invalid.
+
 CLVM is an extensible on-chain programming language, so adding new operators is not a large technical challenge.
 
 ## Backwards Compatibility
 
-* This CHIP requires extensive use of the [softfork](https://chialisp.com/operators/#softfork) operator
+A few notes regarding this CHIP's compatibility with the current implementation of CLVM:
 * The CLVM operators to be added are backwards compatible -- any calls that succeed after the CHIP has been implemented also would have succeeded beforehand
 * The CLVM operators to be added are not forward compatible -- some calls that succeed before the CHIP has been implemented will no longer succeed afterward
 * Because of the forward incompatibility of the operators to be added, this CHIP will require a soft fork of Chia's blockchain
-* The block height of the soft fork will need to be determined before this CHIP can be finalized
 * The operators to be added are unlikely to be contentious. However, as with all forks, there will be a risk of a chain split
 * The soft fork could also fail to be adopted. This might happen if an insufficient number of nodes have upgraded to include the changes introduced by this CHIP prior to the fork's block height
 
+The operators will be introduced in multiple phases:
+* **Pre-CHIP**: Prior to block [todo], any attempt to call the new operators will result in a successful no-op
+* **Soft fork**: A soft fork will activate at block [todo]. From that block forward, the new operators will exhibit the functionality laid out in this CHIP. They will need to be called with the new syntax of the [softfork](https://chialisp.com/operators/#softfork) operator (from inside the `softfork` guard). This syntax is explained in the [Specification](#specification) section of this CHIP
+* **Hard fork**: A hard fork will activate at block [todo]. This hard fork is a result of CHIP-12, which is otherwise unrelated to this CHIP. From block [todo] forward, the operators introduced in this CHIP may also be called without using the `softfork` operator (from outside the `softfork` guard). In other words, the new operators will be added to the core CLVM operator set. (Note that the operators will still be callable from inside the `softfork` guard if desired)
+
 ## Rationale
 
 This CHIP's design was primarily chosen for its standardized implementation. It includes consistent methods for adding, subtracting, multiplying and negating BLS points of every type. In keeping with this consistency, this proposal also includes a mapping from `point_add` to `bls_g1_add`.
@@ -59,7 +65,9 @@ Each of the new operators will incur a CLVM cost, as detailed below. If this CHI
 To support the complete set of available BLS operations within the CLVM, math primitives on G1, G2 and Gt points are required, along with functions for pairing and mapping those points. Therefore, the following operators will be added:
 
 ### bls_g1_add
-
+
+Opcode: [todo]
+
 Functionality: Add two or more G1 points
 
 Note: This operator is already implemented in CLVM as [`point_add`](https://chialisp.com/operators#bls12-381). For consistency and ease of use, a new compiler macro will be created to map `point_add` to `bls_g1_add` so either name can be used with full backward compatibility.
@@ -72,6 +80,8 @@ CLVM Cost: `101 094` base, `1 343 980` per argument
 
 ### bls_g1_subtract
 
+Opcode: [todo]
+
 Functionality: Subtract one or more G1 points from a base G1 point
 
 Arguments: The base G1 point (point1), followed by one or more G1 points to subtract from the base G1 point
@@ -82,6 +92,8 @@ CLVM Cost: `132 332` base, `1 362 553` per argument
 
 ### bls_g1_multiply
 
+Opcode: [todo]
+
 Functionality: Multiply a G1 point by a scalar value
 
 Arguments: A single G1 point (point1) and a single scalar value (scalar)
@@ -92,6 +104,8 @@ CLVM Cost: `2 154 347` base, `12` per byte in the scalar
 
 ### bls_g1_negate
 
+Opcode: [todo]
+
 Functionality: Negate a G1 point
 
 Arguments: A single G1 point
@@ -100,6 +114,8 @@ Usage: `(bls_g1_negate point1)`
 
 CLVM Cost: `470 779`
 
+Opcode: [todo]
+
 ### bls_g2_add
 
 Functionality: Add two or more G2 points
@@ -112,6 +128,8 @@ CLVM Cost: `45 440` base, `5 544 581` per argument
 
 ### bls_g2_subtract
 
+Opcode: [todo]
+
 Functionality: Subtract one or more G2 points from a base G2 point
 
 Arguments: The base G2 point (point1), followed by one or more G2 points to subtract from the base G2 point
@@ -122,6 +140,8 @@ CLVM Cost: `146 290` base, `5 495 272` per argument
 
 ### bls_g2_multiply
 
+Opcode: [todo]
+
 Functionality: Multiply a G2 point by a scalar value
 
 Arguments: A single G2 point (point1) and a single scalar value (scalar)
@@ -132,6 +152,8 @@ CLVM Cost: `10 078 145` base, `12` per byte in the scalar
 
 ### bls_g2_negate
 
+Opcode: [todo]
+
 Functionality: Negate a G2 point
 
 Arguments: A single G2 point
@@ -142,6 +164,8 @@ CLVM Cost: `1 881 699`
 
 ### bls_gt_add
 
+Opcode: [todo]
+
 Functionality: Add two or more Gt points
 
 Arguments: Two or more Gt points
@@ -152,6 +176,8 @@ CLVM Cost: `60 118` base, `62 655 353` per argument
 
 ### bls_gt_subtract
 
+Opcode: [todo]
+
 Functionality: Subtract one or more Gt points from a base Gt point
 
 Arguments: The base Gt point (point1), followed by one or more Gt points to subtract from the base Gt point
@@ -162,6 +188,8 @@ CLVM Cost: `42 927` base, `63 060 911` per argument
 
 ### bls_gt_multiply
 
+Opcode: [todo]
+
 Functionality: Multiply a Gt point by a scalar value
 
 Arguments: A single Gt point (point1) and a single scalar value (scalar)
@@ -172,6 +200,8 @@ CLVM Cost: `34 026 598` base, `12` per byte in the scalar
 
 ### bls_gt_negate
 
+Opcode: [todo]
+
 Functionality: Negate a Gt point
 
 Arguments: A single Gt point
@@ -182,6 +212,8 @@ CLVM Cost: `21 787 950`
 
 ### bls_pairing
 
+Opcode: [todo]
+
 Functionality: Perform pairings between G1 and G2 points; return a Gt value
 
 Arguments: To perform a single pairing, a single pair of G1 and G2 points. To perform multiple pairings, a list of tuples to perform multiple pairings
@@ -194,6 +226,8 @@ CLVM Cost: `4 999 087` base, `4 515 438` per G1/G2 pair
 
 ### bls_map_g1
 
+Opcode: [todo]
+
 Functionality: Map arbitrary data to a G1 point. SSWU and SHA256 hashing are performed on the data 
 
 Arguments: The first argument (required) is the data; the second argument (optional) is a custom DST. If the second argument is not used, the default DST of `BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_NUL_` will be used instead
@@ -204,6 +238,8 @@ CLVM Cost: `610 907` base, `122` per byte, `135` per DST byte
 
 ### bls_map_g2
 
+Opcode: [todo]
+
 Functionality: Map arbitrary data to a G2 point
 
 Arguments: The first argument (required) is the data; the second argument (optional) is a custom DST. If the second argument is not used, the default DST of `BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_NUL_` will be used instead
@@ -212,6 +248,73 @@ Usage: `(bls_map_g2 data dst)`
 
 CLVM Cost: `3 380 023` base, `122` per byte, `135` per DST byte
 
+---
+
+In addition, the following function will be added to calculate a coin ID:
+
+### coinid
+
+Opcode: 48
+
+Functionality: Given a parent coin ID, puzzle-hash and amount, calculate this coin's ID. Also validates arguments, ensuring hashes are 32 bytes, and `amount` is in canonical representation and in the range of valid coins. Raises an exception if any of the arguments are invalid
+
+Arguments:
+
+- `parent-id` -- The coin ID of this coin's parent coin
+- `puzzle-hash` -- The puzzle-hash of this coin's puzzle
+- `amount` -- The value of this coin, in mojos
+
+All three of these arguments are required.
+
+Usage: `(coinid parent-id puzzle-hash amount)`
+
+CLVM Cost: [todo]
+
+---
+
+### `softfork` usage
+
+As explained in the [Backwards compatibility](#backwards-compatibility) section, starting with block [todo] (inclusive), the operators introduced in this CHIP will be available from inside the `softfork` guard.
+
+Note that starting from block [todo], the operators in this CHIP will also be available from outside the `softfork` guard (they will become part of the CLVM in a hard fork). After this point, it will be optional to call the operators from this CHIP from inside the `softfork` guard.
+
+Also note that the syntax of the `softfork` operator has been updated. The following rules apply when calling the operators from this CHIP using the updated `softfork` operator:
+* The operator works like `apply` (`a`) but takes two additional parameters, `cost` and `extension`
+* The syntax is therefore `softfork (<cost> <extension> <quoted-program> <arguments>)`
+* The `cost` parameter is the CLVM cost of executing the `quoted-program` with the specified `arguments`. If this cost mismatches the actual cost of executing the program, the `softfork` operator will raise an exception
+* The `extension` parameter is an integer indicating the set of extensions available in the `softfork` guard. This integer must fit in an unsigned 32-bit variable
+* Just like the `a` operator, the `quoted-program` parameter is quoted and executed from inside the `softfork` guard.
+* A client that does not recognize the `extension` specifier must:
+  * In consensus mode, ignore the whole `softfork`, return `null` and charge the specified `cost`
+  * In mempool mode, fail the program immediately
+
+Since `softfork` guards always return null, the only useful outcome of executing one is terminating (i.e. failing) the program or not.
+
+The cost of executing the `softfork` operator is 140. This counts against the cost specified in its arguments.
+
+An example of using the `softfork` operator to call the new `coinid` operator is as follows:
+
+```
+(softfork
+  (q . 1265) ; expected cost (including cost of softfork itself)
+  (q . 0)    ; extension 0
+  (q a       ; defer execution of if-branches
+    (i
+      (=
+        (coinid
+          (q . 0x1234500000000000000000000000000000000000000000000000000000000000)
+          (q . 0x6789abcdef000000000000000000000000000000000000000000000000000000)
+          (q . 123456789)
+        )
+        (q . 0x69bfe81b052bfc6bd7f3fb9167fec61793175b897c16a35827f947d5cc98e4bc)
+      )
+      (q . 0)  ; if coin ID matches, return 0
+      (q x)    ; if coin ID mismatches, raise
+    )
+    (q . ())) ; environment to apply
+  (q . ()))   ; environment to softfork
+```
+
 ## Test Cases
 
 None so far. New test cases will be added here as they are created.