add clarifications and restrictions to CoinbaseOutputConstraints

Author: plebhash

07-Template-Distribution-Protocol.md

@@ -12,20 +12,49 @@ Template Providers MUST attempt to broadcast blocks which are mined using work t
 
 ## 7.1 `CoinbaseOutputConstraints` (Client -> Server)
 
-Ultimately, the pool is responsible for adding coinbase transaction outputs for payouts and other uses, and thus the Template Provider will need to consider this additional block size, and sigops when selecting transactions for inclusion in a block (to not create an invalid, oversized block).
-Thus, this message is used to indicate that some additional space and sigops in the block/coinbase transaction be reserved for the pool’s use (while always assuming the pool will use the entirety of available coinbase space and sigops).
+When crafting a template, the Template Provider needs to reserve appropriate blockspace and sigops for the Coinbase Transaction (to not create an invalid, oversized block). Here's a table with all fields of a Coinbase Transaction that have fixed size:
+
+| field name               | size                 | weight factor | weight |
+|--------------------------|----------------------|---------------|--------|
+| `version`                | 4 bytes              | 4 WU/byte     | 16 WU  |
+| `marker` + `flag`        | 2 bytes (if SegWit)  | 4 WU/byte     | 8 WU   |
+| `input count`            | 1 byte               | 4 WU/byte     | 4 WU   |
+| `prev txid`              | 32 bytes             | 4 WU/byte     | 128 WU |
+| `input index`            | 4 bytes              | 4 WU/byte     | 16 WU  |
+| `scriptSig length`       | 1 byte               | 4 WU/byte     | 4 WU   |
+| `input sequence`         | 4 bytes              | 4 WU/byte     | 16 WU  |
+| `witness count`          | 1 byte (if SegWit)   | 1 WU/byte     | 1 WU   |
+| `witness length`         | 1 byte (if SegWit)   | 1 WU/byte     | 1 WU   |
+| `witness reserved value` | 32 bytes (if SegWit) | 1 WU/byte     | 32 WU  |
+| `locktime`               | 4 bytes              | 4 WU/byte     | 16 WU  |
+
+So a Template Provider MUST reserve 242 weight units for the fixed-size fields in case of a SegWit block, or 200 weight units in the unlikely case of a legacy block. Meanwhile, the following fields of a Coinbase Transaction have variable size:
+
+| field name     | size          | weight factor | weight     |
+|----------------|---------------|---------------|------------|
+| `scriptSig`    | 100 bytes max | 4 WU/byte     | 400 WU max |
+| `output count` | 9 bytes max   | 4 WU/byte     | 46 WU max  |
+| `outputs`      | no limit      | 4 WU/byte     | no limit   |
+
+So a Template Provider MUST also reserve:
+- the worst-case 400 weight units for `scriptSig` field
+- the worst-case 46 weight units for `output count` field
+- 188 weight units for witness commitment output
+
+But ultimately, the Pool (or JDC, in case of Job Declaration) is responsible for adding coinbase transaction outputs for payouts and other uses, and thus the Template Provider will need to consider this additional block size, and sigops when selecting transactions for inclusion in a block.
+
+Thus, the `CoinbaseOutputConstraints` message is used to indicate that some additional space and sigops in the block/coinbase transaction be reserved for the Pool or JDC use (while always assuming the entirety of available coinbase space and sigops will be used).
+
+JDC MUST discover the maximum serialized size of the additional outputs and sigops which will be added by the Pool(s) it intends to use this work with (via `AllocateMiningJobToken.Success`). It then MUST communicate it to the Template Provider via `CoinbaseOutputConstraints`.
 
-The Job Declarator MUST discover the maximum serialized size of the additional outputs and sigops which will be added by the pool(s) it intends to use this work.
-It then MUST communicate it to the Template Provider via this message.
 The Template Provider MUST NOT provide `NewTemplate` messages which would represent consensus-invalid blocks once this additional size and sigops — along with a maximally-sized (100 byte) coinbase script field — is added.
-Further, the Template Provider MUST consider the maximum additional bytes required in the output count variable-length integer in the coinbase transaction when complying with the size limits.
-Current sigops limit per block in bitcoin is 80_000. We are not aware of any use cases where
-coinbase have more the 65_535 so coinbase_output_max_sigops is an U16. Note that taproot outputs consume 0 sigops.
+
+Current sigops limit per block in bitcoin is `80_000`. We are not aware of any use cases where a coinbase transaction has more than `65_535` so `coinbase_output_max_sigops` is an `U16`. Note that taproot outputs consume `0` sigops.
 
 | Field Name                            | Data Type | Description                                                                                     |
 | ------------------------------------- | --------- | ----------------------------------------------------------------------------------------------- |
-| coinbase_output_max_additional_size   | U32       | The maximum additional serialized bytes which the pool will add in coinbase transaction outputs |
-| coinbase_output_max_additional_sigops | U16       | The maximum additional sigops which the pool will add in coinbase transaction outputs           |
+| coinbase_output_max_additional_size   | U32       | The maximum additional serialized bytes which Pool or JDC will add in coinbase transaction outputs |
+| coinbase_output_max_additional_sigops | U16       | The maximum additional sigops which Pool or JDC will add in coinbase transaction outputs           |
 
 ## 7.2 `NewTemplate` (Server -> Client)