merge-queue: embarking main (726f732) and [#5107 + #5138 + #5176] together

.github/workflows/build-docker-image.yml

@@ -71,15 +71,16 @@ jobs:
           # list of Docker images to use as base name for tags
           images: |
             us-docker.pkg.dev/zealous-zebra/zebra/${{ inputs.image_name }}
+            zfnd/zebra,enable=${{ github.event_name == 'release' && !github.event.release.prerelease }}
           # generate Docker tags based on the following events/attributes
           tags: |
             type=schedule
-            type=sha
-            type=ref,event=branch
-            type=ref,event=pr
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
+            type=ref,event=branch
+            type=ref,event=pr
+            type=sha
 
       # Setup Docker Buildx to allow use of docker cache layers from GH
       - name: Set up Docker Buildx
@@ -105,9 +106,17 @@ jobs:
           registry: us-docker.pkg.dev
           username: oauth2accesstoken
           password: ${{ steps.auth.outputs.access_token }}
-          logout: false
 
-      # Build and push image to Google Artifact Registry
+      - name: Login to DockerHub
+        # We only publish images to DockerHub if a release is not a pre-release
+        # Ref: https://github.com/orgs/community/discussions/26281#discussioncomment-3251177
+        if: ${{ github.event_name == 'release' && !github.event.release.prerelease }}
+        uses: docker/[email protected]
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Build and push image to Google Artifact Registry, and possibly DockerHub
       - name: Build & push
         id: docker_build
         uses: docker/[email protected]

.github/workflows/release-binaries.yml

@@ -0,0 +1,34 @@
+# This workflow is meant to trigger a build of Docker binaries when a release
+# is published, it uses the existing `build-docker-image.yml` workflow
+#
+# We use a separate action as we might want to trigger this under
+# different circumstances than a Continuous Deployment, for example.
+#
+# This workflow is triggered if:
+# - A release is published
+# - A pre-release is changed to a release
+name: Release binaries
+
+on:
+  release:
+    types:
+      - released
+
+jobs:
+  # Each time this workflow is executed, a build will be triggered to create a new image
+  # with the corresponding tags using information from git
+  #
+  # The image will be named `zebrad:<semver>`
+  build:
+    uses: ./.github/workflows/build-docker-image.yml
+    with:
+      dockerfile_path: ./docker/Dockerfile
+      dockerfile_target: runtime
+      image_name: zebrad
+      network: Mainnet
+      checkpoint_sync: true
+      rust_backtrace: '1'
+      zebra_skip_ipv6_tests: '1'
+      rust_log: info
+    # This step needs access to Docker Hub secrets to run successfully
+    secrets: inherit

zebra-rpc/src/methods.rs

@@ -916,7 +916,7 @@ where
                     data: None,
                 })?;
             let utxos = match response {
-                zebra_state::ReadResponse::Utxos(utxos) => utxos,
+                zebra_state::ReadResponse::AddressUtxos(utxos) => utxos,
                 _ => unreachable!("unmatched response to a UtxosByAddresses request"),
             };
 

zebra-state/src/request.rs

@@ -445,9 +445,11 @@ pub enum Request {
     /// [`block::Height`] using `.into()`.
     Block(HashOrHeight),
 
-    /// Request a UTXO identified by the given
-    /// [`OutPoint`](transparent::OutPoint), waiting until it becomes available
-    /// if it is unknown.
+    /// Request a UTXO identified by the given [`OutPoint`](transparent::OutPoint),
+    /// waiting until it becomes available if it is unknown.
+    ///
+    /// Checks the finalized chain, all non-finalized chains, queued unverified blocks,
+    /// and any blocks that arrive at the state after the request future has been created.
     ///
     /// This request is purely informational, and there are no guarantees about
     /// whether the UTXO remains unspent or is on the best chain, or any chain.
@@ -458,6 +460,8 @@ pub enum Request {
     /// UTXO requests should be wrapped in a timeout, so that
     /// out-of-order and invalid requests do not hang indefinitely. See the [`crate`]
     /// documentation for details.
+    ///
+    /// Outdated requests are pruned on a regular basis.
     AwaitUtxo(transparent::OutPoint),
 
     /// Finds the first hash that's in the peer's `known_blocks` and the local best chain.
@@ -542,6 +546,24 @@ pub enum ReadRequest {
     /// * [`ReadResponse::Transaction(None)`](ReadResponse::Transaction) otherwise.
     Transaction(transaction::Hash),
 
+    /// Looks up a UTXO identified by the given [`OutPoint`](transparent::OutPoint),
+    /// returning `None` immediately if it is unknown.
+    ///
+    /// Checks verified blocks in the finalized chain and the _best_ non-finalized chain.
+    ///
+    /// This request is purely informational, there is no guarantee that
+    /// the UTXO remains unspent in the best chain.
+    BestChainUtxo(transparent::OutPoint),
+
+    /// Looks up a UTXO identified by the given [`OutPoint`](transparent::OutPoint),
+    /// returning `None` immediately if it is unknown.
+    ///
+    /// Checks verified blocks in the finalized chain and _all_ non-finalized chains.
+    ///
+    /// This request is purely informational, there is no guarantee that
+    /// the UTXO remains unspent in the best chain.
+    AnyChainUtxo(transparent::OutPoint),
+
     /// Computes a block locator object based on the current best chain.
     ///
     /// Returns [`ReadResponse::BlockLocator`] with hashes starting
@@ -662,8 +684,6 @@ impl TryFrom<Request> for ReadRequest {
             Request::Block(hash_or_height) => Ok(ReadRequest::Block(hash_or_height)),
             Request::Transaction(tx_hash) => Ok(ReadRequest::Transaction(tx_hash)),
 
-            Request::AwaitUtxo(_) => unimplemented!("use StoredUtxo here"),
-
             Request::BlockLocator => Ok(ReadRequest::BlockLocator),
             Request::FindBlockHashes { known_blocks, stop } => {
                 Ok(ReadRequest::FindBlockHashes { known_blocks, stop })
@@ -675,6 +695,10 @@ impl TryFrom<Request> for ReadRequest {
             Request::CommitBlock(_) | Request::CommitFinalizedBlock(_) => {
                 Err("ReadService does not write blocks")
             }
+
+            Request::AwaitUtxo(_) => Err("ReadService does not track pending UTXOs. \
+                     Manually convert the request to ReadRequest::AnyChainUtxo, \
+                     and handle pending UTXOs"),
         }
     }
 }

zebra-state/src/response.rs

@@ -39,7 +39,8 @@ pub enum Response {
     /// Response to [`Request::Block`] with the specified block.
     Block(Option<Arc<Block>>),
 
-    /// The response to a `AwaitUtxo` request.
+    /// The response to a `AwaitUtxo` request, from any non-finalized chains, finalized chain,
+    /// pending unverified blocks, or blocks received after the request was sent.
     Utxo(transparent::Utxo),
 
     /// The response to a `FindBlockHashes` request.
@@ -75,6 +76,20 @@ pub enum ReadResponse {
     /// The response to a `FindBlockHeaders` request.
     BlockHeaders(Vec<block::CountedHeader>),
 
+    /// The response to a `BestChainUtxo` request, from verified blocks in the
+    /// _best_ non-finalized chain, or the finalized chain.
+    ///
+    /// This response is purely informational, there is no guarantee that
+    /// the UTXO remains unspent in the best chain.
+    BestChainUtxo(Option<transparent::Utxo>),
+
+    /// The response to an `AnyChainUtxo` request, from verified blocks in
+    /// _any_ non-finalized chain, or the finalized chain.
+    ///
+    /// This response is purely informational, there is no guarantee that
+    /// the UTXO remains unspent in the best chain.
+    AnyChainUtxo(Option<transparent::Utxo>),
+
     /// Response to [`ReadRequest::SaplingTree`] with the specified Sapling note commitment tree.
     SaplingTree(Option<Arc<sapling::tree::NoteCommitmentTree>>),
 
@@ -89,7 +104,7 @@ pub enum ReadResponse {
     AddressesTransactionIds(BTreeMap<TransactionLocation, transaction::Hash>),
 
     /// Response to [`ReadRequest::UtxosByAddresses`] with found utxos and transaction data.
-    Utxos(AddressUtxos),
+    AddressUtxos(AddressUtxos),
 }
 
 /// Conversion from read-only [`ReadResponse`]s to read-write [`Response`]s.
@@ -108,17 +123,21 @@ impl TryFrom<ReadResponse> for Response {
                 Ok(Response::Transaction(tx_and_height.map(|(tx, _height)| tx)))
             }
 
+            ReadResponse::AnyChainUtxo(_) => Err("ReadService does not track pending UTXOs. \
+                                                  Manually unwrap the response, and handle pending UTXOs."),
+
             ReadResponse::BlockLocator(hashes) => Ok(Response::BlockLocator(hashes)),
             ReadResponse::BlockHashes(hashes) => Ok(Response::BlockHashes(hashes)),
             ReadResponse::BlockHeaders(headers) => Ok(Response::BlockHeaders(headers)),
 
-            ReadResponse::SaplingTree(_) => unimplemented!(),
-            ReadResponse::OrchardTree(_) => unimplemented!(),
-
-            ReadResponse::AddressBalance(_) => unimplemented!(),
-            ReadResponse::AddressesTransactionIds(_) => unimplemented!(),
-            // TODO: Rename to AddressUtxos
-            ReadResponse::Utxos(_) => unimplemented!(),
+            ReadResponse::BestChainUtxo(_)
+            | ReadResponse::SaplingTree(_)
+            | ReadResponse::OrchardTree(_)
+            | ReadResponse::AddressBalance(_)
+            | ReadResponse::AddressesTransactionIds(_)
+            | ReadResponse::AddressUtxos(_) => {
+                Err("there is no corresponding Response for this ReadResponse")
+            }
         }
     }
 }