[doc/architecture/payment] payment spec

doc/src/architecture/payment/burn.md

@@ -0,0 +1,36 @@
+# burn contract
+
+$$ X = (nullifier, cm^{value}_x, cm^{value}_y, cm^{token}, root, data, spendHook, signature^{public}_x, signature^{public}_y) $$
+
+$$ W = (value, token, blind^{value}, blind^{token}, sn, spendHook, data, blind^{data}, sk, pos^{leaf}, path, signature^{secret}) $$
+
+$$ \mathcal{L} = \{X:W\in \mathcal{R}\} $$
+
+
+| Public Input         | Description                                             |
+|----------------------|---------------------------------------------------------|
+| nullifier            | hash of (secretKey||serial)                             |
+| $cm^{value}_x        | x coordinate of value point commitment                  |
+| $cm^{value}_y        | y coordinate of value point commitment                  |
+| $cm^{token}          | commitment of tokenId as field element                  |
+| root                 | root of commitments tree                                |
+| data                 | data read during execution of burn spendHook contract   |
+| spendHook            | burn related contract                                   |
+|$signature^{public}_x$| signature public x coordinate                           |
+|$signature^{public}_y$| signature public y coordinate                           |
+
+
+| witnesses            | Description                                         |
+|----------------------|-----------------------------------------------------|
+| value                | burn value                                          |
+| token                | token id                                            |
+| $blind^{value}$      | blinding term for burn value commitment             |
+| $blind^{token}$      | blinding term for token id commitment               |
+| sn                   | serial number for burn coin                         |
+| spendHook            | contract related contract                           |
+| data                 | data read during spendHook execution                |
+| $blind^{data}$       | blinding term for data commitment                   |
+| sk                   | coin private key                                    |
+| $pos^{leaf}$         | coin commitment leaf position in the merkle tree    |
+| path                 | coin commitment merkle tree path                    |
+| $signature^{secret}$ | signature secret key                                |

doc/src/architecture/payment/coin.md

@@ -0,0 +1,13 @@
+# coin
+
+field element commitment to $(pub_x, pub_y, value, token, sn, spendHook, data)$
+
+| coin array           | Description                                       |
+|----------------------|---------------------------------------------------|
+| $pub_x$              | public key x coordinate                           |
+| $pub_y$              | public key y coordinate                           |
+| value                | coin value                                        |
+| token                | coin token id                                     |
+| sn                   | coin serial number                                |
+| spendHook            | contract to be executed upon minting that coin    |
+| data                 | data required by spendHook                        |

doc/src/architecture/payment/freeze_token.md

@@ -0,0 +1,19 @@
+# freeze token
+
+burn minted coins
+
+$$ X = (authority^{public}_x, authority^{public}_y, token) $$
+
+$$ W = (authority^{secret}) $$
+
+$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+
+| Public Input         | Description                                             |
+|----------------------|---------------------------------------------------------|
+|$authority^{public}_y$| minting authority public key y-coordinate               |
+|$authority^{public}_x$| minting authority public key x-coordinate               |
+| token                | derived token id                                        |
+
+| witnesses            | Description                                         |
+|----------------------|-----------------------------------------------------|
+| $authority^{secret}  | minting authority secret key                        |

doc/src/architecture/payment/mint.md

@@ -0,0 +1,26 @@
+# mint contract
+
+$$ X = (cm^{coin}, cm^{value}_x, cm^{value}_y, cm^{token} $$
+
+$$ W = (pk_x, pk_y, value, token, sn, spendHook, data, blind^{value}, blind^{token}) $$
+
+$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+
+| Public Input         | Description                                             |
+|----------------------|---------------------------------------------------------|
+| $cm^{coin}$          | coin commitment as field element                        |
+| $cm^{value}_x        | x coordinate of value point commitment                  |
+| $cm^{value}_y        | y coordinate of value point commitment                  |
+| $cm^{token}          | commitment of tokenId as field element                  |
+
+| witnesses            | Description                                         |
+|----------------------|-----------------------------------------------------|
+| $pk_x$               | coin public key x coordinate                        |
+| $pk_y$               | coin public key y coordinate                        |
+| value                | burn value                                          |
+| token                | token id                                            |
+| sn                   | serial number for burn coin                         |
+| spendHook            | contract related contract                           |
+| data                 | data read during spendHook execution                |
+| $blind^{value}$      | blinding term for burn value commitment             |
+| $blind^{token}$      | blinding term for token id commitment               |

doc/src/architecture/payment/payment.md

@@ -0,0 +1,5 @@
+# payment
+
+implements zcash sapling payment scheme [^1], payment involve burning old sender's coin, and mint new recipient coin.
+
+[^1]: https://zips.z.cash/protocol/protocol.pdf

doc/src/architecture/payment/token_id.md

@@ -0,0 +1,8 @@
+# Token Id
+
+each token has unique token id derived as:
+$$ hash(PREFIX || key^{public}_x || key^{public}_y) $$
+`key` is authority key, or public key.
+
+%# validate unique id
+%validate newly minted tokens doesn't match any token mint transaction's token Id.

doc/src/architecture/payment/token_mint.md

@@ -0,0 +1,33 @@
+# arbitrary token mint
+
+mint new tokens with arbitrary supply to given recipient.
+
+# new token mint
+
+$$ X = (authority^{public}_x, authority^{public}_y, token, cm^{coin}, cm^{value}_x, cm^{value}_y), cm^{token} $$
+
+$$ W = (authority^{secret}, value, rcpt_x, rcpt_y, sn, spendHook, data, blind^{value}, blind^{token}) $$
+
+$$ \mathcal{L}= \{X:W\in \mathcal{R}\} $$
+
+| Public Input         | Description                                             |
+|----------------------|---------------------------------------------------------|
+|$authority^{public}_y$| minting authority public key y-coordinate               |
+|$authority^{public}_x$| minting authority public key x-coordinate               |
+| token                | derived token id                                        |
+| $cm^{coin}$          | coin commitment as field element                        |
+| $cm^{value}_x        | x coordinate of supply point commitment                 |
+| $cm^{value}_y        | y coordinate of supply point commitment                 |
+| $cm^{token}          | commitment of tokenId as field element                  |
+
+| witnesses            | Description                                         |
+|----------------------|-----------------------------------------------------|
+| $authority^{secret}  | minting authority secret key                        |
+| value                | token minted supply value                           |
+| $rcpt_x$             | token recipient public key x coordinate             |
+| $rcpt_y$             | token recipient public key y coordinate             |
+| sn                   | serial number for burn coin                         |
+| spendHook            | contract related contract                           |
+| data                 | data read during spendHook execution                |
+| $blind^{value}$      | blinding term for burn value commitment             |
+| $blind^{token}$      | blinding term for token id commitment               |