Merge pull request #106 from jannotti/algorand-v4

Changes for block incentives and v11 opcodes

dev/TEAL.md

@@ -60,9 +60,6 @@ assembly time to do type checking and to provide more informative error messages
 
 | Name | Bound | AVM Type |
 | ---- | ---- | -------- |
-| [32]byte | len(x) == 32 | []byte |
-| [64]byte | len(x) == 64 | []byte |
-| [80]byte | len(x) == 80 | []byte |
 | []byte | len(x) <= 4096 | []byte |
 | address | len(x) == 32 | []byte |
 | any |  | any |
@@ -158,7 +155,7 @@ Each opcode has an associated cost, usually 1, but a few slow operations
 have higher costs. Prior to v4, the program's cost was estimated as the
 static sum of all the opcode costs in the program (whether they were
 actually executed or not). Beginning with v4, the program's cost is
-tracked dynamically, while being evaluated. If the program exceeds its
+tracked dynamically while being evaluated. If the program exceeds its
 budget, it fails.
 
 The total program cost of all Smart Signatures in a group must not
@@ -490,6 +487,7 @@ these results may contain leading zero bytes.
 | `ec_multi_scalar_mul g` | for curve points A and scalars B, return curve point B0A0 + B1A1 + B2A2 + ... + BnAn |
 | `ec_subgroup_check g` | 1 if A is in the main prime-order subgroup of G (including the point at infinity) else 0. Program fails if A is not in G at all. |
 | `ec_map_to g` | maps field element A to group G |
+| `mimc c` | MiMC hash of scalars A, using curve and parameters specified by configuration C |
 
 ### Loading Values
 
@@ -646,6 +644,11 @@ Global fields are fields that are common to all the transactions in the group. I
 | 15 | AssetCreateMinBalance | uint64 | v10  | The additional minimum balance required to create (and opt-in to) an asset. |
 | 16 | AssetOptInMinBalance | uint64 | v10  | The additional minimum balance required to opt-in to an asset. |
 | 17 | GenesisHash | [32]byte | v10  | The Genesis Hash for the network. |
+| 18 | PayoutsEnabled | bool | v11  | Whether block proposal payouts are enabled. |
+| 19 | PayoutsGoOnlineFee | uint64 | v11  | The fee required in a keyreg transaction to make an account incentive eligible. |
+| 20 | PayoutsPercent | uint64 | v11  | The percentage of transaction fees in a block that can be paid to the block proposer. |
+| 21 | PayoutsMinBalance | uint64 | v11  | The minimum algo balance an account must have in the agreement round to receive block payouts in the proposal round. |
+| 22 | PayoutsMaxBalance | uint64 | v11  | The maximum algo balance an account can have in the agreement round to receive block payouts in the proposal round. |
 
 
 **Asset Fields**
@@ -709,6 +712,9 @@ Account fields used in the `acct_params_get` opcode.
 | 9 | AcctTotalAssets | uint64 | v8  | The numbers of ASAs held by this account (including ASAs this account created). |
 | 10 | AcctTotalBoxes | uint64 | v8  | The number of existing boxes created by this account's app. |
 | 11 | AcctTotalBoxBytes | uint64 | v8  | The total number of bytes used by this account's app's box keys and values. |
+| 12 | AcctIncentiveEligible | bool | v11  | Has this account opted into block payouts |
+| 13 | AcctLastProposed | uint64 | v11  | The round number of the last block this account proposed. |
+| 14 | AcctLastHeartbeat | uint64 | v11  | The round number of the last block this account sent a heartbeat. |
 
 
 ### Flow Control
@@ -759,6 +765,8 @@ Account fields used in the `acct_params_get` opcode.
 | `asset_params_get f` | X is field F from asset A. Y is 1 if A exists, else 0 |
 | `app_params_get f` | X is field F from app A. Y is 1 if A exists, else 0 |
 | `acct_params_get f` | X is field F from account A. Y is 1 if A owns positive algos, else 0 |
+| `voter_params_get f` | X is field F from online account A as of the balance round: 320 rounds before the current round. Y is 1 if A had positive algos online in the agreement round, else Y is 0 and X is a type specific zero-value |
+| `online_stake` | the total online stake in the agreement round |
 | `log` | write A to log state of the current application |
 | `block f` | field F of block A. Fail unless A falls between txn.LastValid-1002 and txn.FirstValid (exclusive) |
 

dev/TEAL_opcodes.md

@@ -6,7 +6,7 @@ abstract: >
   Algorand allows transactions to be effectively signed by a small program. If the program evaluates to true then the transaction is allowed. This document defines the language opcodes and byte encoding.
 ---
 
-# v10 Opcodes
+# v11 Opcodes
 
 Ops have a 'cost' of 1 unless otherwise specified.
 
@@ -51,7 +51,7 @@ The 32 byte public key is the last element on the stack, preceded by the 64 byte
 
 - Syntax: `ecdsa_verify V` where V: [ECDSA](#field-group-ecdsa)
 - Bytecode: 0x05 {uint8}
-- Stack: ..., A: [32]byte, B: []byte, C: []byte, D: []byte, E: []byte → ..., bool
+- Stack: ..., A: [32]byte, B: [32]byte, C: [32]byte, D: [32]byte, E: [32]byte → ..., bool
 - for (data A, signature B, C and pubkey D, E) verify the signature of the data against the pubkey => {0 or 1}
 - **Cost**: Secp256k1=1700; Secp256r1=2500
 - Availability: v5
@@ -72,7 +72,7 @@ The 32 byte Y-component of a public key is the last element on the stack, preced
 
 - Syntax: `ecdsa_pk_decompress V` where V: [ECDSA](#field-group-ecdsa)
 - Bytecode: 0x06 {uint8}
-- Stack: ..., A: []byte → ..., X: []byte, Y: []byte
+- Stack: ..., A: [33]byte → ..., X: [32]byte, Y: [32]byte
 - decompress pubkey A into components X, Y
 - **Cost**: Secp256k1=650; Secp256r1=2400
 - Availability: v5
@@ -83,7 +83,7 @@ The 33 byte public key in a compressed form to be decompressed into X and Y (top
 
 - Syntax: `ecdsa_pk_recover V` where V: [ECDSA](#field-group-ecdsa)
 - Bytecode: 0x07 {uint8}
-- Stack: ..., A: [32]byte, B: uint64, C: [32]byte, D: [32]byte → ..., X: []byte, Y: []byte
+- Stack: ..., A: [32]byte, B: uint64, C: [32]byte, D: [32]byte → ..., X: [32]byte, Y: [32]byte
 - for (data A, recovery id B, signature C, D) recover a public key
 - **Cost**: 2000
 - Availability: v5
@@ -183,7 +183,7 @@ Overflow is an error condition which halts execution and fails the transaction.
 ## itob
 
 - Bytecode: 0x16
-- Stack: ..., A: uint64 → ..., []byte
+- Stack: ..., A: uint64 → ..., [8]byte
 - converts uint64 A to big-endian byte array, always of length 8
 
 ## btoi
@@ -470,6 +470,11 @@ Fields
 | 15 | AssetCreateMinBalance | uint64 | v10  | The additional minimum balance required to create (and opt-in to) an asset. |
 | 16 | AssetOptInMinBalance | uint64 | v10  | The additional minimum balance required to opt-in to an asset. |
 | 17 | GenesisHash | [32]byte | v10  | The Genesis Hash for the network. |
+| 18 | PayoutsEnabled | bool | v11  | Whether block proposal payouts are enabled. |
+| 19 | PayoutsGoOnlineFee | uint64 | v11  | The fee required in a keyreg transaction to make an account incentive eligible. |
+| 20 | PayoutsPercent | uint64 | v11  | The percentage of transaction fees in a block that can be paid to the block proposer. |
+| 21 | PayoutsMinBalance | uint64 | v11  | The minimum algo balance an account must have in the agreement round to receive block payouts in the proposal round. |
+| 22 | PayoutsMaxBalance | uint64 | v11  | The maximum algo balance an account can have in the agreement round to receive block payouts in the proposal round. |
 
 
 ## gtxn
@@ -904,7 +909,7 @@ params: Txn.Accounts offset (or, since v4, an _available_ account address), _ava
 ## app_local_get
 
 - Bytecode: 0x62
-- Stack: ..., A, B: []byte → ..., any
+- Stack: ..., A, B: stateKey → ..., any
 - local state of the key B in the current application in account A
 - Availability: v2
 - Mode: Application
@@ -914,7 +919,7 @@ params: Txn.Accounts offset (or, since v4, an _available_ account address), stat
 ## app_local_get_ex
 
 - Bytecode: 0x63
-- Stack: ..., A, B: uint64, C: []byte → ..., X: any, Y: bool
+- Stack: ..., A, B: uint64, C: stateKey → ..., X: any, Y: bool
 - X is the local state of application B, key C in account A. Y is 1 if key existed, else 0
 - Availability: v2
 - Mode: Application
@@ -924,7 +929,7 @@ params: Txn.Accounts offset (or, since v4, an _available_ account address), _ava
 ## app_global_get
 
 - Bytecode: 0x64
-- Stack: ..., A: []byte → ..., any
+- Stack: ..., A: stateKey → ..., any
 - global state of the key A in the current application
 - Availability: v2
 - Mode: Application
@@ -934,7 +939,7 @@ params: state key. Return: value. The value is zero (of type uint64) if the key
 ## app_global_get_ex
 
 - Bytecode: 0x65
-- Stack: ..., A: uint64, B: []byte → ..., X: any, Y: bool
+- Stack: ..., A: uint64, B: stateKey → ..., X: any, Y: bool
 - X is the global state of application A, key B. Y is 1 if key existed, else 0
 - Availability: v2
 - Mode: Application
@@ -944,7 +949,7 @@ params: Txn.ForeignApps offset (or, since v4, an _available_ application id), st
 ## app_local_put
 
 - Bytecode: 0x66
-- Stack: ..., A, B: []byte, C → ...
+- Stack: ..., A, B: stateKey, C → ...
 - write C to key B in account A's local state of the current application
 - Availability: v2
 - Mode: Application
@@ -954,15 +959,15 @@ params: Txn.Accounts offset (or, since v4, an _available_ account address), stat
 ## app_global_put
 
 - Bytecode: 0x67
-- Stack: ..., A: []byte, B → ...
+- Stack: ..., A: stateKey, B → ...
 - write B to key A in the global state of the current application
 - Availability: v2
 - Mode: Application
 
 ## app_local_del
 
 - Bytecode: 0x68
-- Stack: ..., A, B: []byte → ...
+- Stack: ..., A, B: stateKey → ...
 - delete key B from account A's local state of the current application
 - Availability: v2
 - Mode: Application
@@ -974,7 +979,7 @@ Deleting a key which is already absent has no effect on the application local st
 ## app_global_del
 
 - Bytecode: 0x69
-- Stack: ..., A: []byte → ...
+- Stack: ..., A: stateKey → ...
 - delete key A from the global state of the current application
 - Availability: v2
 - Mode: Application
@@ -1090,7 +1095,37 @@ Fields
 | 9 | AcctTotalAssets | uint64 | v8  | The numbers of ASAs held by this account (including ASAs this account created). |
 | 10 | AcctTotalBoxes | uint64 | v8  | The number of existing boxes created by this account's app. |
 | 11 | AcctTotalBoxBytes | uint64 | v8  | The total number of bytes used by this account's app's box keys and values. |
+| 12 | AcctIncentiveEligible | bool | v11  | Has this account opted into block payouts |
+| 13 | AcctLastProposed | uint64 | v11  | The round number of the last block this account proposed. |
+| 14 | AcctLastHeartbeat | uint64 | v11  | The round number of the last block this account sent a heartbeat. |
+
+
+## voter_params_get
+
+- Syntax: `voter_params_get F` where F: [voter_params](#field-group-voter_params)
+- Bytecode: 0x74 {uint8}
+- Stack: ..., A → ..., X: any, Y: bool
+- X is field F from online account A as of the balance round: 320 rounds before the current round. Y is 1 if A had positive algos online in the agreement round, else Y is 0 and X is a type specific zero-value
+- Availability: v11
+- Mode: Application
 
+### voter_params
+
+Fields
+
+| Index | Name | Type | Notes |
+| - | ------ | -- | --------- |
+| 0 | VoterBalance | uint64 | Online stake in microalgos |
+| 1 | VoterIncentiveEligible | bool | Had this account opted into block payouts |
+
+
+## online_stake
+
+- Bytecode: 0x75
+- Stack: ... → ..., uint64
+- the total online stake in the agreement round
+- Availability: v11
+- Mode: Application
 
 ## min_balance
 
@@ -1262,7 +1297,7 @@ bitlen interprets arrays as big-endian integers, unlike setbit/getbit
 ## bsqrt
 
 - Bytecode: 0x96
-- Stack: ..., A: []byte → ..., []byte
+- Stack: ..., A: bigint → ..., bigint
 - The largest integer I such that I^2 <= A. A and I are interpreted as big-endian unsigned integers
 - **Cost**: 40
 - Availability: v6
@@ -1279,7 +1314,7 @@ The notation A,B indicates that A and B are interpreted as a uint128 value, with
 ## sha3_256
 
 - Bytecode: 0x98
-- Stack: ..., A: []byte &rarr; ..., []byte
+- Stack: ..., A: []byte &rarr; ..., [32]byte
 - SHA3_256 hash of value A, yields [32]byte
 - **Cost**: 130
 - Availability: v7
@@ -1361,7 +1396,7 @@ The notation A,B indicates that A and B are interpreted as a uint128 value, with
 ## b%
 
 - Bytecode: 0xaa
-- Stack: ..., A: []byte, B: []byte &rarr; ..., []byte
+- Stack: ..., A: bigint, B: bigint &rarr; ..., bigint
 - A modulo B. A and B are interpreted as big-endian unsigned integers. Fail if B is zero.
 - **Cost**: 20
 - Availability: v4
@@ -1616,7 +1651,7 @@ For boxes that exceed 4,096 bytes, consider `box_create`, `box_extract`, and `bo
 
 - Syntax: `vrf_verify S` where S: [vrf_verify](#field-group-vrf_verify)
 - Bytecode: 0xd0 {uint8}
-- Stack: ..., A: []byte, B: [80]byte, C: [32]byte &rarr; ..., X: []byte, Y: bool
+- Stack: ..., A: []byte, B: [80]byte, C: [32]byte &rarr; ..., X: [64]byte, Y: bool
 - Verify the proof B of message A against pubkey C. Returns vrf output and verification flag.
 - **Cost**: 5700
 - Availability: v7
@@ -1644,10 +1679,18 @@ Standards
 
 Fields
 
-| Index | Name | Type | Notes |
-| - | ------ | -- | --------- |
-| 0 | BlkSeed | []byte |  |
-| 1 | BlkTimestamp | uint64 |  |
+| Index | Name | Type | In | Notes |
+| - | ------ | -- | - | --------- |
+| 0 | BlkSeed | [32]byte |      |  |
+| 1 | BlkTimestamp | uint64 |      |  |
+| 2 | BlkProposer | address | v11  |  |
+| 3 | BlkFeesCollected | uint64 | v11  |  |
+| 4 | BlkBonus | uint64 | v11  |  |
+| 5 | BlkBranch | [32]byte | v11  |  |
+| 6 | BlkFeeSink | address | v11  |  |
+| 7 | BlkProtocol | []byte | v11  |  |
+| 8 | BlkTxnCounter | uint64 | v11  |  |
+| 9 | BlkProposerPayout | uint64 | v11  |  |
 
 
 ## box_splice
@@ -1754,3 +1797,26 @@ The name `ec_multi_scalar_mul` was chosen to reflect common usage, but a more co
 
 BN254 points are mapped by the SVDW map. BLS12-381 points are mapped by the SSWU map.
 G1 element inputs are base field elements and G2 element inputs are quadratic field elements, with nearly the same encoding rules (for field elements) as defined in `ec_add`. There is one difference of encoding rule: G1 element inputs do not need to be 0-padded if they fit in less than 32 bytes for BN254 and less than 48 bytes for BLS12-381. (As usual, the empty byte array represents 0.) G2 elements inputs need to be always have the required size.
+
+## mimc
+
+- Syntax: `mimc C` where C: [Mimc Configurations](#field-group-mimc configurations)
+- Bytecode: 0xe6 {uint8}
+- Stack: ..., A: []byte &rarr; ..., [32]byte
+- MiMC hash of scalars A, using curve and parameters specified by configuration C
+- **Cost**: BN254Mp110=10 + 550 per 32 bytes of A; BLS12_381Mp111=10 + 550 per 32 bytes of A
+- Availability: v11
+
+### Mimc Configurations
+
+Parameters
+
+| Index | Name | Notes |
+| - | ------ | --------- |
+| 0 | BN254Mp110 | MiMC configuration for the BN254 curve with Miyaguchi-Preneel mode, 110 rounds, exponent 5, seed "seed" |
+| 1 | BLS12_381Mp111 | MiMC configuration for the BLS12-381 curve with Miyaguchi-Preneel mode, 111 rounds, exponent 5, seed "seed" |
+
+
+A is a list of concatenated 32 byte big-endian unsigned integer scalars.  Fail if A's length is not a multiple of 32 or any element exceeds the curve modulus.
+
+The MiMC hash function has known collisions since any input which is a multiple of the elliptic curve modulus will hash to the same value. MiMC is thus not a general purpose hash function, but meant to be used in zero knowledge applications to match a zk-circuit implementation.