feat(rpc): tag Zebra-mined blocks with a 🦓 coinbase marker (#10836)

Author: upbqdn

.github/workflows/test-docker.yml

@@ -111,7 +111,7 @@ jobs:
           - id: custom-conf
             name: Custom config
             env_vars: -v $GITHUB_WORKSPACE/zebrad/tests/common/configs/custom-conf.toml:/tmp/custom-conf.toml:ro -e CONFIG_FILE_PATH=/tmp/custom-conf.toml
-            grep_patterns: -e "extra_coinbase_data:\\sSome\\(\\\"Do you even shield\\?\\\"\\)"
+            grep_patterns: -e "extra_coinbase_data:\\sSome\\(ExtraCoinbaseData\\(\\\"Do you even shield\\?\\\"\\)\\)"
 
           # RPC configuration tests
           - id: rpc-conf

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 ### Added
 
+- Zebra now tags the coinbase input of every block it mines with a `🦓`. The
+  `mining.extra_coinbase_data` option is now limited to 86 bytes (was 94); Zebra
+  refuses to start if it is exceeded.
 - Pre-built `zebrad` binaries are attached to each GitHub release for Linux on
   `x86_64` and `aarch64`, so operators can run a node without Docker or a source
   build, also installable with `cargo binstall zebrad`. Each `.tar.gz` carries a

book/src/user/mining.md

@@ -61,22 +61,21 @@ If `miner_address` is a Unified Address with more than one receiver, Zebra sends
 
 [#extra-coinbase-data]: #extra-coinbase-data
 
-Zebra does not tag its blocks by default. If you don't set `extra_coinbase_data`, the blocks you mine carry no identifying data. Setting this option fixes that:
+Zebra prepends a `🦓` marker to the coinbase input of every block it builds. Setting `extra_coinbase_data` adds your own tag (such as a pool name) after it, separated by `": "`:
 
 ```toml
 [mining]
 miner_address = 't3dvVE3SQEi7kqNzwrfNePxZ1d4hUyztBA1'
 extra_coinbase_data = "/MyPoolName/"
 ```
 
-A few important details about how this value is used:
+How it's used:
 
-- The string is inserted into the transparent input script of the coinbase transaction, immediately after the encoded block height.
-- The string is always encoded as raw UTF-8 bytes. It is **not** hex-decoded, even if it looks like a valid hex string — `extra_coinbase_data = "deadbeef"` puts the eight ASCII characters `deadbeef` in the coinbase script, not the four bytes `0xde 0xad 0xbe 0xef`. This option only carries UTF-8 text, so arbitrary non-UTF-8 byte sequences can't be embedded. In practice most mining tags are short, human-readable pool names or identifiers, so this is usually what you want anyway.
-- The encoded value, including Zebra's script push overhead, is limited to 94 bytes. Because that limit includes 1-2 bytes of push-opcode overhead, keep your tag at 92 bytes or less to be safe. If the limit is exceeded, Zebra refuses to build a block template until the value is shortened.
-- This field is optional. Leaving it unset is valid — Zebra just won't tag the block.
+- Inserted into the coinbase input script, after the block height, `🦓` marker, and `": "` separator.
+- Limited to 86 bytes. If exceeded, Zebra refuses to start.
+- Optional. If unset, the block still carries the `🦓` marker, just no extra data.
 
-You can confirm the tag is being applied by calling `getblocktemplate` and checking the `coinbasetxn.data` field (see [Testing the setup](#testing-the-setup)): the hex string after the height bytes should decode back to your configured text.
+You can confirm the marker is applied by calling `getblocktemplate` and checking the `coinbasetxn.data` field (see [Testing the setup](#testing-the-setup)): after the height bytes you'll see the `🦓` marker (`f0 9f a6 93`), then — if `extra_coinbase_data` is set — the `": "` separator (`3a 20`) and your text.
 
 ### Miner memo
 

zebra-rpc/CHANGELOG.md

@@ -14,9 +14,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The indexer `NonFinalizedStateChange` subscription accepts the caller's known chain
   tip hashes and streams only the blocks above them, so a re-subscribing consumer
   resumes instead of being sent the entire non-finalized state again.
+- `config::mining::ExtraCoinbaseData` and `config::mining::ExtraCoinbaseDataTooLong`.
 
 ### Changed
 
+- Zebra now prepends a `🦓` marker to the coinbase input of every block it builds.
+- `config::mining::Config::extra_coinbase_data` is now `Option<ExtraCoinbaseData>` (was
+  `Option<String>`), limited to 86 bytes (was 94) and validated on construction.
 - The read-state syncer (`TrustedChainSync`) applies backpressure to the non-finalized
   block stream instead of dropping blocks for a slow consumer, bridges the gap between
   a lagging finalized tip and the streamed non-finalized chain by fetching the missing

zebra-rpc/src/config/mining.rs

@@ -1,14 +1,34 @@
 //! Mining config
 
-use std::collections::HashMap;
+use std::{collections::HashMap, ops::Deref};
 
-use serde::{Deserialize, Serialize};
+use serde::{de, Deserialize, Deserializer, Serialize, Serializer};
 use serde_with::{serde_as, DisplayFromStr};
 
 use strum_macros::EnumIter;
 use zcash_address::ZcashAddress;
+use zcash_transparent::coinbase::{MAX_COINBASE_HEIGHT_LEN, MAX_COINBASE_SCRIPT_LEN};
 use zebra_chain::parameters::NetworkKind;
 
+/// The maximum length of the optional, arbitrary data in the script sig field of a coinbase tx.
+pub(crate) const MAX_MINER_DATA_LEN: usize = MAX_COINBASE_SCRIPT_LEN - MAX_COINBASE_HEIGHT_LEN;
+
+/// The marker Zebra prepends to the coinbase input of every block it builds.
+///
+/// The zebra emoji (`U+1F993`), 4 UTF-8 bytes.
+pub(crate) const ZEBRA_COINBASE_MARKER: &str = "🦓";
+
+/// Separates [`ZEBRA_COINBASE_MARKER`] from `extra_coinbase_data`. Present only when that is set.
+pub(crate) const ZEBRA_COINBASE_SEPARATOR: &str = ": ";
+
+/// The maximum length of the user-configurable `extra_coinbase_data`.
+///
+/// The coinbase data is the marker, separator, and user data in a single push, so the user
+/// portion is [`MAX_MINER_DATA_LEN`] minus the marker, separator, and the 2-byte `OP_PUSHDATA1`
+/// opcode (for pushes over 75 bytes).
+pub(crate) const MAX_USER_COINBASE_DATA_LEN: usize =
+    MAX_MINER_DATA_LEN - ZEBRA_COINBASE_MARKER.len() - ZEBRA_COINBASE_SEPARATOR.len() - 2;
+
 /// Mining configuration section.
 #[serde_as]
 #[derive(Clone, Debug, Default, Eq, PartialEq, Deserialize, Serialize)]
@@ -20,12 +40,11 @@ pub struct Config {
     #[serde_as(as = "Option<DisplayFromStr>")]
     pub miner_address: Option<ZcashAddress>,
 
-    /// Optional data that Zebra will include in the transparent input of a coinbase transaction.
+    /// Optional tag that Zebra appends to the coinbase input of every block it builds, after the
+    /// Zebra `🦓` marker and a `: ` separator.
     ///
-    /// The string is always encoded as raw UTF-8 bytes; it is not hex-decoded, even if it looks
-    /// like a valid hex string. The encoded value, including Zebra's script push overhead, is
-    /// limited to 94 bytes.
-    pub extra_coinbase_data: Option<String>,
+    /// Limited to `MAX_USER_COINBASE_DATA_LEN` bytes.
+    pub extra_coinbase_data: Option<ExtraCoinbaseData>,
 
     /// Optional shielded memo that Zebra will include in the output of a shielded coinbase
     /// transaction. Limited to 512 bytes.
@@ -54,6 +73,58 @@ impl Config {
     }
 }
 
+/// Operator-configured data appended to the coinbase input of every block Zebra builds, after
+/// Zebra's `🦓` marker and `: ` separator.
+///
+/// Validated on construction to fit within the coinbase data budget, so an oversized value can't
+/// be represented — and an oversized `mining.extra_coinbase_data` in the config makes Zebra fail
+/// to start.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ExtraCoinbaseData(String);
+
+impl Deref for ExtraCoinbaseData {
+    type Target = str;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+/// The error returned when [`ExtraCoinbaseData`] is constructed from too many bytes.
+#[derive(Clone, Debug, thiserror::Error)]
+#[error("extra_coinbase_data is {0} bytes, but the maximum is {MAX_USER_COINBASE_DATA_LEN}")]
+pub struct ExtraCoinbaseDataTooLong(usize);
+
+impl TryFrom<String> for ExtraCoinbaseData {
+    type Error = ExtraCoinbaseDataTooLong;
+
+    fn try_from(data: String) -> Result<Self, Self::Error> {
+        if data.len() > MAX_USER_COINBASE_DATA_LEN {
+            Err(ExtraCoinbaseDataTooLong(data.len()))
+        } else {
+            Ok(Self(data))
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for ExtraCoinbaseData {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        Self::try_from(String::deserialize(deserializer)?).map_err(de::Error::custom)
+    }
+}
+
+impl Serialize for ExtraCoinbaseData {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        self.0.serialize(serializer)
+    }
+}
+
 /// The desired address type for the `mining.miner_address` field in the config.
 #[derive(EnumIter, Eq, PartialEq, Default, Hash)]
 pub enum MinerAddressType {

zebra-rpc/src/methods/tests/snapshots/get_block_template_basic.coinbase_tx@mainnet_10.snap

@@ -9,7 +9,13 @@ V5(
   inputs: [
     Coinbase(
       height: Height(1687105),
-      data: [],
+      data: [
+        4,
+        240,
+        159,
+        166,
+        147,
+      ],
       sequence: 4294967295,
     ),
   ],

zebra-rpc/src/methods/tests/snapshots/get_block_template_basic.coinbase_tx@testnet_10.snap

@@ -9,7 +9,13 @@ V5(
   inputs: [
     Coinbase(
       height: Height(1842421),
-      data: [],
+      data: [
+        4,
+        240,
+        159,
+        166,
+        147,
+      ],
       sequence: 4294967295,
     ),
   ],

zebra-rpc/src/methods/tests/snapshots/get_block_template_basic@mainnet_10.snap

@@ -8,20 +8,20 @@ expression: block_template
   ],
   "version": 4,
   "previousblockhash": "0000000000d723156d9b65ffcf4984da7a19675ed7e2f06d9e5d5188af087bf8",
-  "blockcommitmentshash": "fe03d8236b0835c758f59d279230ebaee2128754413103b9edb17c07451c2c82",
-  "lightclientroothash": "fe03d8236b0835c758f59d279230ebaee2128754413103b9edb17c07451c2c82",
-  "finalsaplingroothash": "fe03d8236b0835c758f59d279230ebaee2128754413103b9edb17c07451c2c82",
+  "blockcommitmentshash": "9fe0f2f50842e3d0d5c4b78554ead8bfaa3314241f6f899d2373b96a3aaecccd",
+  "lightclientroothash": "9fe0f2f50842e3d0d5c4b78554ead8bfaa3314241f6f899d2373b96a3aaecccd",
+  "finalsaplingroothash": "9fe0f2f50842e3d0d5c4b78554ead8bfaa3314241f6f899d2373b96a3aaecccd",
   "defaultroots": {
     "merkleroot": "0dd4c87d6aba52431fef01079578826b547a22e444af986368c507918f893e8a",
     "chainhistoryroot": "94470fa66ebd1a5fdb109a5aa3f3204f14de3a42135e71aa7f4c44055847e0b5",
-    "authdataroot": "0dbb78de9fdcd494307971e36dd049fc82d0ee9ee53aec8fd2a54dc0e426289b",
-    "blockcommitmentshash": "fe03d8236b0835c758f59d279230ebaee2128754413103b9edb17c07451c2c82"
+    "authdataroot": "c1b58477fa048262b10f726bf451dc8476e55fc56d82a5792a0ba63d0e2f645d",
+    "blockcommitmentshash": "9fe0f2f50842e3d0d5c4b78554ead8bfaa3314241f6f899d2373b96a3aaecccd"
   },
   "transactions": [],
   "coinbasetxn": {
-    "data": "050000800a27a726b4d0d6c20000000041be1900010000000000000000000000000000000000000000000000000000000000000000ffffffff040341be19ffffffff0480b2e60e0000000017a9147e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e87286bee000000000017a914d45cb1adffb5215a42720532a076f02c7c778c908738c94d010000000017a91469a9f95a98fe581b6eb52841ef4806dc4402eb908740787d010000000017a914931fec54c1fea86e574462cc32013f5400b8912987000000",
+    "data": "050000800a27a726b4d0d6c20000000041be1900010000000000000000000000000000000000000000000000000000000000000000ffffffff090341be1904f09fa693ffffffff0480b2e60e0000000017a9147e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e87286bee000000000017a914d45cb1adffb5215a42720532a076f02c7c778c908738c94d010000000017a91469a9f95a98fe581b6eb52841ef4806dc4402eb908740787d010000000017a914931fec54c1fea86e574462cc32013f5400b8912987000000",
     "hash": "0dd4c87d6aba52431fef01079578826b547a22e444af986368c507918f893e8a",
-    "authdigest": "0dbb78de9fdcd494307971e36dd049fc82d0ee9ee53aec8fd2a54dc0e426289b",
+    "authdigest": "c1b58477fa048262b10f726bf451dc8476e55fc56d82a5792a0ba63d0e2f645d",
     "depends": [],
     "fee": 0,
     "sigops": 0,

zebra-rpc/src/methods/tests/snapshots/get_block_template_basic@testnet_10.snap

@@ -8,20 +8,20 @@ expression: block_template
   ],
   "version": 4,
   "previousblockhash": "0000000000d723156d9b65ffcf4984da7a19675ed7e2f06d9e5d5188af087bf8",
-  "blockcommitmentshash": "cb1f1c6a5ad5ff9c4a170e3b747a24f3aec79817adba9a9451f19914481bb422",
-  "lightclientroothash": "cb1f1c6a5ad5ff9c4a170e3b747a24f3aec79817adba9a9451f19914481bb422",
-  "finalsaplingroothash": "cb1f1c6a5ad5ff9c4a170e3b747a24f3aec79817adba9a9451f19914481bb422",
+  "blockcommitmentshash": "09b60daeec8adbd96a08459e35f142fac3ac7ea5c5fb218f521c9da8b3428f91",
+  "lightclientroothash": "09b60daeec8adbd96a08459e35f142fac3ac7ea5c5fb218f521c9da8b3428f91",
+  "finalsaplingroothash": "09b60daeec8adbd96a08459e35f142fac3ac7ea5c5fb218f521c9da8b3428f91",
   "defaultroots": {
     "merkleroot": "453e5aa76d390b623e714cad2658c219393b3019e639e8d477f91eca7697b62b",
     "chainhistoryroot": "03bc75f00c307a05aed2023819e18c2672cbe15fbd3200944997def141967387",
-    "authdataroot": "a44375f0c0dd5ba612bd7b0efd77683cde8edf5055aff9fbfda443cc8d46bd3e",
-    "blockcommitmentshash": "cb1f1c6a5ad5ff9c4a170e3b747a24f3aec79817adba9a9451f19914481bb422"
+    "authdataroot": "9e7e7313dee920062d78f2f738c6d127b303c5f4649cd9a1b92a955c06c02fe4",
+    "blockcommitmentshash": "09b60daeec8adbd96a08459e35f142fac3ac7ea5c5fb218f521c9da8b3428f91"
   },
   "transactions": [],
   "coinbasetxn": {
-    "data": "050000800a27a726b4d0d6c200000000f51c1c00010000000000000000000000000000000000000000000000000000000000000000ffffffff0403f51c1cffffffff0480b2e60e0000000017a9147e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e87286bee000000000017a9140c0bcca02f3cba01a5d7423ac3903d40586399eb8738c94d010000000017a9144e3f0d9a33a2721604cbae2de8d9171e21f8fbe48740787d010000000017a91471e1df05024288a00802de81e08c437859586c8787000000",
+    "data": "050000800a27a726b4d0d6c200000000f51c1c00010000000000000000000000000000000000000000000000000000000000000000ffffffff0903f51c1c04f09fa693ffffffff0480b2e60e0000000017a9147e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e7e87286bee000000000017a9140c0bcca02f3cba01a5d7423ac3903d40586399eb8738c94d010000000017a9144e3f0d9a33a2721604cbae2de8d9171e21f8fbe48740787d010000000017a91471e1df05024288a00802de81e08c437859586c8787000000",
     "hash": "453e5aa76d390b623e714cad2658c219393b3019e639e8d477f91eca7697b62b",
-    "authdigest": "a44375f0c0dd5ba612bd7b0efd77683cde8edf5055aff9fbfda443cc8d46bd3e",
+    "authdigest": "9e7e7313dee920062d78f2f738c6d127b303c5f4649cd9a1b92a955c06c02fe4",
     "depends": [],
     "fee": 0,
     "sigops": 0,

zebra-rpc/src/methods/tests/snapshots/get_block_template_long_poll.coinbase_tx@mainnet_10.snap

@@ -9,7 +9,13 @@ V5(
   inputs: [
     Coinbase(
       height: Height(1687105),
-      data: [],
+      data: [
+        4,
+        240,
+        159,
+        166,
+        147,
+      ],
       sequence: 4294967295,
     ),
   ],