feat: claimable builder fees

docs/source/builder-integration.rst

@@ -240,6 +240,29 @@ Querying Match Events
         print(f"Sequencer Fee: {match.sequencer_fee}")
         print(f"Builder Fee: {match.builder_fee}")
 
+Querying Claimable Fees
+-----------------------
+
+Before claiming, check how much you've accumulated using ``get_claimable_builder_fee``:
+
+.. code-block:: python
+
+    from nado_protocol.contracts import NadoContracts, NadoContractsContext
+    from nado_protocol.contracts.loader import load_deployment
+
+    deployment = load_deployment("mainnet")  # or "testnet"
+    nado_contracts = NadoContracts(
+        node_url=deployment.node_url,
+        contracts_context=NadoContractsContext(**deployment.dict()),
+    )
+
+    builder_id = 2  # Your builder ID
+    claimable = nado_contracts.get_claimable_builder_fee(builder_id)
+    print(f"Claimable: {claimable / 1e18} USDC")
+
+This calls the ``getClaimableBuilderFee(quoteId, builderId)`` view function on the OffchainExchange contract.
+The return value is in **x18 format** (divide by 10^18 to get USDC), e.g. ``5000000000000000000`` = 5 USDC.
+
 Claiming Builder Fees
 ---------------------
 
@@ -446,6 +469,7 @@ Slow Mode Functions
 Contract Methods
 ~~~~~~~~~~~~~~~~
 
+- :meth:`nado_protocol.contracts.NadoContracts.get_claimable_builder_fee` - Query claimable fee amount
 - :meth:`nado_protocol.contracts.NadoContracts.claim_builder_fee` - Claim accumulated builder fees
 - :meth:`nado_protocol.contracts.NadoContracts.get_builder_info` - Query builder configuration
 

docs/source/conf.py

@@ -65,5 +65,6 @@
 autosummary_generate = True
 
 html_favicon = "nado.ico"
+html_logo = "nado-icon.svg"
 
 pygments_style = "sphinx"

nado_protocol/contracts/__init__.py

@@ -340,6 +340,26 @@ def claim_builder_fee(
             signer,
         )
 
+    def get_claimable_builder_fee(self, builder_id: int) -> int:
+        """
+        Gets the claimable builder fee for a given builder ID.
+
+        Args:
+            builder_id (int): The builder ID to query.
+
+        Returns:
+            int: The claimable fee amount in x18 format (divide by 1e18 to get USDC).
+
+        Raises:
+            Exception: If the OffchainExchange contract is not initialized.
+        """
+        if self.offchain_exchange is None:
+            raise Exception("OffchainExchange contract not initialized")
+
+        return self.offchain_exchange.functions.getClaimableBuilderFee(
+            0, builder_id
+        ).call()
+
     def get_builder_info(self, builder_id: int) -> BuilderInfo:
         """
         Gets builder information from the OffchainExchange contract.

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "nado-protocol"
-version = "0.3.3"
+version = "0.3.4"
 description = "Nado Protocol SDK"
 authors = ["Jeury Mejia <jeury@inkfnd.com>"]
 homepage = "https://nado.xyz"