feat(api): improve proof ergonomics

Bind fetched non-inclusion proofs to their requested state IDs and add explicit verification for decoded proofs. Add proof-carrying membership status, public terminal accessors, typed certificate construction, and an additive non-inclusion client extension trait.

Author: ristik

README.md

@@ -67,10 +67,10 @@ Non-inclusion has a relation-specific API; applications never need to know
 that its Merkle path has internal machinery in common with inclusion:
 
 ```rust
-use unicity_token::client::AggregatorClient;
+use unicity_token::client::NonInclusionAggregatorClient;
 
 let proof = aggregator.get_non_inclusion_proof(&state_id)?;
-proof.verify(&state_id, &trust_base)?;
+proof.verify(&trust_base)?; // verifies the StateId bound by the client
 ```
 
 Verification authenticates the terminal leaf and every branch choice against
@@ -81,6 +81,18 @@ acceptable certified round or timestamp. The HTTP client distinguishes an
 already-included state (`HttpError::StateIncluded`) from the absence of any
 certified root (`HttpError::CertifiedStateUnavailable`).
 
+If the caller does not know which relation holds, the HTTP client hides the
+endpoint selection:
+
+```rust
+use unicity_token::client::MembershipStatus;
+
+match aggregator.membership_status(&state_id)? {
+    MembershipStatus::Included(proof) => proof.verify_for(&state_id, &trust_base)?,
+    MembershipStatus::Absent(proof) => proof.verify(&trust_base)?,
+}
+```
+
 ## Payment tokens & splits
 
 A token can carry a fungible **payment payload** (a canonical set of asset id →

src/api/inclusion_proof.rs

@@ -3,13 +3,15 @@
 
 use alloc::vec::Vec;
 
-use super::bft::UnicityCertificate;
+use super::bft::{RootTrustBase, UnicityCertificate};
 use super::certification::CertificationData;
 use super::inclusion_certificate::InclusionCertificate;
+use super::StateId;
 use crate::cbor::{
     encode_array, encode_byte_string, encode_nullable, encode_tag, encode_uint, Decoder,
 };
 use crate::error::Error;
+use crate::verify::{self, VerificationError};
 
 /// CBOR tag for [`InclusionProof`].
 pub const INCLUSION_PROOF_TAG: u64 = 39033;
@@ -59,4 +61,17 @@ impl InclusionProof {
             ]),
         )
     }
+
+    /// Verify that this proof includes `state_id` at its certified root.
+    ///
+    /// This verifies the state relation, certification data, shard, quorum UC,
+    /// and unlock witness. Transaction/token verification may impose additional
+    /// application-level constraints.
+    pub fn verify_for(
+        &self,
+        state_id: &StateId,
+        trust_base: &RootTrustBase,
+    ) -> Result<(), VerificationError> {
+        verify::verify_inclusion_proof_for(trust_base, self, state_id)
+    }
 }

src/api/non_inclusion_certificate.rs

@@ -32,6 +32,40 @@ struct Body {
 }
 
 impl NonInclusionCertificate {
+    /// Construct the distinguished certificate for an empty tree.
+    pub fn empty_tree() -> Self {
+        Self { body: None }
+    }
+
+    /// Construct a non-empty certificate from its typed components.
+    ///
+    /// Siblings are ordered root-to-leaf and their count must equal the bitmap
+    /// population count. The fixed terminal-value width is a Unicity profile
+    /// restriction; the generic RSMT format permits arbitrary byte strings.
+    pub fn from_parts(
+        bitmap: [u8; BITMAP_SIZE],
+        siblings: Vec<[u8; HASH_SIZE]>,
+        terminal_key: [u8; TERMINAL_KEY_SIZE],
+        terminal_value: [u8; AGGREGATION_TREE_VALUE_SIZE],
+    ) -> Result<Self, Error> {
+        let expected = bitmap.iter().map(|byte| byte.count_ones()).sum::<u32>() as usize;
+        if siblings.len() != expected {
+            return Err(Error::InvalidLength {
+                what: "NonInclusionCertificate siblings",
+                expected,
+                actual: siblings.len(),
+            });
+        }
+        Ok(Self {
+            body: Some(Body {
+                bitmap,
+                siblings,
+                terminal_key,
+                terminal_value,
+            }),
+        })
+    }
+
     /// Decode the canonical raw-byte representation.
     ///
     /// The empty byte string is the distinguished certificate for an empty
@@ -40,7 +74,7 @@ impl NonInclusionCertificate {
     /// where `n` is the bitmap population count.
     pub fn decode(bytes: &[u8]) -> Result<Self, Error> {
         if bytes.is_empty() {
-            return Ok(Self { body: None });
+            return Ok(Self::empty_tree());
         }
         if bytes.len() < BITMAP_SIZE {
             return Err(Error::InvalidLength {
@@ -92,14 +126,7 @@ impl NonInclusionCertificate {
             .try_into()
             .expect("length checked");
 
-        Ok(Self {
-            body: Some(Body {
-                bitmap,
-                siblings,
-                terminal_key,
-                terminal_value,
-            }),
-        })
+        Self::from_parts(bitmap, siblings, terminal_key, terminal_value)
     }
 
     /// Encode to the canonical raw-byte representation.
@@ -123,10 +150,26 @@ impl NonInclusionCertificate {
     }
 
     /// Whether this is the distinguished certificate for an empty tree.
-    pub fn is_empty(&self) -> bool {
+    pub fn is_empty_tree(&self) -> bool {
         self.body.is_none()
     }
 
+    /// The authenticated terminal key, or `None` for an empty-tree certificate.
+    ///
+    /// Treat this as untrusted data until certificate or proof verification has
+    /// succeeded.
+    pub fn terminal_key(&self) -> Option<&[u8; TERMINAL_KEY_SIZE]> {
+        self.body.as_ref().map(|body| &body.terminal_key)
+    }
+
+    /// The authenticated terminal value, or `None` for an empty-tree certificate.
+    ///
+    /// Treat this as untrusted data until certificate or proof verification has
+    /// succeeded.
+    pub fn terminal_value(&self) -> Option<&[u8; AGGREGATION_TREE_VALUE_SIZE]> {
+        self.body.as_ref().map(|body| &body.terminal_value)
+    }
+
     /// Verify both the authenticated path and the non-inclusion relation.
     /// `expected_root` is `None` only for an empty certified tree.
     ///
@@ -167,10 +210,6 @@ impl NonInclusionCertificate {
             .as_ref()
             .is_some_and(|body| &body.terminal_key == target.bytes())
     }
-
-    pub(crate) fn terminal_key(&self) -> Option<&[u8; TERMINAL_KEY_SIZE]> {
-        self.body.as_ref().map(|body| &body.terminal_key)
-    }
 }
 
 #[cfg(test)]
@@ -196,9 +235,9 @@ mod tests {
 
     #[test]
     fn empty_certificate_only_verifies_empty_root() {
-        let certificate = NonInclusionCertificate::decode(&[]).unwrap();
+        let certificate = NonInclusionCertificate::empty_tree();
         let target = state_id([7u8; 32]);
-        assert!(certificate.is_empty());
+        assert!(certificate.is_empty_tree());
         assert_eq!(certificate.verify(&target, None), Ok(()));
         assert_eq!(
             certificate.verify(&target, Some(&leaf_root(&[1; 32], &[2; 32]))),
@@ -211,10 +250,16 @@ mod tests {
     fn singleton_terminal_proves_another_key_absent() {
         let terminal_key = [1u8; 32];
         let terminal_value = [2u8; 32];
+        let certificate = NonInclusionCertificate::from_parts(
+            [0u8; BITMAP_SIZE],
+            vec![],
+            terminal_key,
+            terminal_value,
+        )
+        .unwrap();
         let mut encoded = vec![0u8; BITMAP_SIZE];
         encoded.extend_from_slice(&terminal_key);
         encoded.extend_from_slice(&terminal_value);
-        let certificate = NonInclusionCertificate::decode(&encoded).unwrap();
         let root = leaf_root(&terminal_key, &terminal_value);
 
         assert_eq!(
@@ -225,6 +270,8 @@ mod tests {
             certificate.verify(&state_id(terminal_key), Some(&root)),
             Err(VerificationError::StateIncluded)
         );
+        assert_eq!(certificate.terminal_key(), Some(&terminal_key));
+        assert_eq!(certificate.terminal_value(), Some(&terminal_value));
         assert_eq!(certificate.encode(), encoded);
     }
 
@@ -245,12 +292,15 @@ mod tests {
             .update(right_hash.data())
             .finalize();
 
-        let mut encoded = vec![0u8; BITMAP_SIZE];
-        encoded[0] = 0x80;
-        encoded.extend_from_slice(right_hash.data());
-        encoded.extend_from_slice(&left_key);
-        encoded.extend_from_slice(&left_value);
-        let certificate = NonInclusionCertificate::decode(&encoded).unwrap();
+        let mut bitmap = [0u8; BITMAP_SIZE];
+        bitmap[0] = 0x80;
+        let certificate = NonInclusionCertificate::from_parts(
+            bitmap,
+            vec![right_hash.data().try_into().expect("SHA-256 length")],
+            left_key,
+            left_value,
+        )
+        .unwrap();
 
         let mut target_left = [0u8; 32];
         target_left[31] = 1;
@@ -270,6 +320,16 @@ mod tests {
 
     #[test]
     fn decoder_rejects_wrong_terminal_or_sibling_lengths() {
+        let mut bitmap = [0u8; BITMAP_SIZE];
+        bitmap[0] = 0x80;
+        assert!(NonInclusionCertificate::from_parts(
+            bitmap,
+            vec![],
+            [1u8; 32],
+            [2u8; AGGREGATION_TREE_VALUE_SIZE],
+        )
+        .is_err());
+
         assert!(NonInclusionCertificate::decode(&[0u8; 32]).is_err());
 
         let mut one_sibling_without_terminal = vec![0u8; 64];

src/api/non_inclusion_proof.rs

@@ -23,6 +23,8 @@ const VERSION: u64 = 1;
 pub struct NonInclusionProof {
     certificate: NonInclusionCertificate,
     unicity_certificate: UnicityCertificate,
+    /// Local request context. This is deliberately not part of the wire format.
+    requested_state_id: Option<StateId>,
 }
 
 impl NonInclusionProof {
@@ -34,6 +36,7 @@ impl NonInclusionProof {
         Self {
             certificate,
             unicity_certificate,
+            requested_state_id: None,
         }
     }
 
@@ -52,6 +55,7 @@ impl NonInclusionProof {
         Ok(Self {
             certificate,
             unicity_certificate,
+            requested_state_id: None,
         })
     }
 
@@ -77,12 +81,57 @@ impl NonInclusionProof {
         &self.unicity_certificate
     }
 
-    /// Verify the complete proof for `target` against `trust_base`.
-    pub fn verify(
+    /// Bind this proof to the state id used to request it.
+    ///
+    /// The binding is local misuse-prevention metadata and is not serialized by
+    /// [`to_cbor`](Self::to_cbor). Verification still authenticates the bound
+    /// id cryptographically against the certificate.
+    pub fn for_state(mut self, state_id: &StateId) -> Result<Self, VerificationError> {
+        if self
+            .requested_state_id
+            .as_ref()
+            .is_some_and(|requested| requested != state_id)
+        {
+            return Err(VerificationError::NonInclusionTargetMismatch);
+        }
+        self.requested_state_id = Some(state_id.clone());
+        Ok(self)
+    }
+
+    /// The state id stamped onto this proof by the client, if any.
+    pub fn requested_state_id(&self) -> Option<&StateId> {
+        self.requested_state_id.as_ref()
+    }
+
+    /// Verify a client-bound proof against `trust_base`.
+    ///
+    /// Proofs returned by the provided clients are bound automatically. A proof
+    /// decoded directly from untrusted bytes has no request context; use
+    /// [`verify_for`](Self::verify_for) for that case.
+    pub fn verify(&self, trust_base: &RootTrustBase) -> Result<(), VerificationError> {
+        let target = self
+            .requested_state_id
+            .as_ref()
+            .ok_or(VerificationError::NonInclusionTargetMissing)?;
+        verify::verify_non_inclusion_proof(trust_base, self, target)
+    }
+
+    /// Verify a directly decoded proof for an explicit `target`.
+    ///
+    /// If the proof is already client-bound, a different target is rejected so
+    /// request context cannot be silently replaced.
+    pub fn verify_for(
         &self,
         target: &StateId,
         trust_base: &RootTrustBase,
     ) -> Result<(), VerificationError> {
+        if self
+            .requested_state_id
+            .as_ref()
+            .is_some_and(|requested| requested != target)
+        {
+            return Err(VerificationError::NonInclusionTargetMismatch);
+        }
         verify::verify_non_inclusion_proof(trust_base, self, target)
     }
 }

src/client/http.rs

@@ -21,7 +21,7 @@ use crate::api::inclusion_proof::InclusionProof;
 use crate::api::{CertificationData, NonInclusionProof, StateId};
 use crate::cbor::Decoder;
 
-use super::AggregatorClient;
+use super::{AggregatorClient, MembershipStatus, NonInclusionAggregatorClient};
 
 const MAX_RESPONSE_BODY_BYTES: usize = 8 * 1024 * 1024;
 const MAX_ERROR_BODY_BYTES: usize = 64 * 1024;
@@ -189,6 +189,22 @@ impl HttpAggregatorClient {
         self
     }
 
+    /// Determine whether `state_id` is included or absent at a certified root.
+    ///
+    /// This hides the endpoint-selection round trip: absence normally takes one
+    /// RPC, while an included state triggers an inclusion-proof lookup after the
+    /// non-inclusion endpoint reports that the relation is false. The two RPCs
+    /// are not an atomic read if the certified root advances between them; each
+    /// returned proof authenticates the root it carries.
+    pub fn membership_status(&self, state_id: &StateId) -> Result<MembershipStatus, HttpError> {
+        match NonInclusionAggregatorClient::get_non_inclusion_proof(self, state_id) {
+            Ok(proof) => Ok(MembershipStatus::Absent(proof)),
+            Err(HttpError::StateIncluded) => AggregatorClient::get_inclusion_proof(self, state_id)
+                .map(MembershipStatus::Included),
+            Err(error) => Err(error),
+        }
+    }
+
     fn validate_endpoint(&self) -> Result<url::Url, HttpError> {
         let parsed = url::Url::parse(&self.url)
             .map_err(|e| HttpError::Configuration(format!("invalid gateway URL: {e}")))?;
@@ -411,7 +427,9 @@ impl AggregatorClient for HttpAggregatorClient {
         }
         Err(HttpError::Timeout)
     }
+}
 
+impl NonInclusionAggregatorClient for HttpAggregatorClient {
     fn get_non_inclusion_proof(&self, state_id: &StateId) -> Result<NonInclusionProof, HttpError> {
         let params = serde_json::json!({ "stateId": hex::encode(state_id.bytes()) });
         let result = match self.rpc("get_non_inclusion_proof.v1", params, &[]) {
@@ -433,7 +451,9 @@ impl AggregatorClient for HttpAggregatorClient {
             });
         }
         let bytes = hex::decode(encoded).map_err(|e| HttpError::Decode(e.to_string()))?;
-        decode_non_inclusion_proof_response(&bytes)
+        decode_non_inclusion_proof_response(&bytes)?
+            .for_state(state_id)
+            .map_err(|error| HttpError::Decode(error.to_string()))
     }
 }