mersennet-sdk 0.1.1__tar.gz

mersennet_sdk-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mersennet Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mersennet_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: mersennet-sdk
+Version: 0.1.1
+Summary: Python SDK for Mersennet: JSON-RPC, the on-chain order book (MersennetOrders precompile), shielded notes and viewing keys
+Author-email: Mersennet Foundation <dev@mersennet.com>
+License: MIT
+Project-URL: Homepage, https://mersennet.com
+Project-URL: Documentation, https://docs.mersennet.com/developers/sdks/python/
+Project-URL: Repository, https://github.com/mersennet/sdk-python
+Project-URL: Issues, https://github.com/mersennet/sdk-python/issues
+Keywords: mersennet,blockchain,evm,order-book,perpetuals,zk,json-rpc,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: websocket-client>=1.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Dynamic: license-file
+
+<p align="center"><a href="https://mersennet.com"><img src="https://raw.githubusercontent.com/mersennet/.github/main/profile/mark.svg" width="72" alt="Mersennet"></a></p>
+<h1 align="center">Mersennet Python SDK</h1>
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-7dff9b?style=flat-square" alt="MIT license"></a>
+  <a href="https://github.com/mersennet/sdk-python/actions/workflows/ci.yml"><img src="https://github.com/mersennet/sdk-python/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://docs.mersennet.com/developers/sdks/python/"><img src="https://img.shields.io/badge/docs-mersennet-1c1c1c?style=flat-square" alt="Docs"></a>
+  <a href="https://t.me/Mersennet"><img src="https://img.shields.io/badge/telegram-%40Mersennet-26A5E4?style=flat-square" alt="Telegram"></a>
+</p>
+
+Python client for Mersennet - JSON-RPC, CLOB (order book), and WebSocket subscriptions.
+
+## Installation
+
+```bash
+pip install "git+https://github.com/mersennet/sdk-python.git@v0.1.0"   # PyPI publication pending
+```
+
+Or from source:
+
+```bash
+cd sdk-python
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from mersennet import MersennetProvider, MersennetOrders
+
+provider = MersennetProvider("http://localhost:8545")
+
+# Chain info
+print("Chain ID:", provider.chain_id())
+print("Block:", provider.block_number())
+print("Gas price:", provider.gas_price())
+
+# Account
+balance = provider.get_balance("0xYourAddress")
+print("Balance:", balance)
+
+# Order book
+orders = MersennetOrders(provider)
+book = orders.get_order_book(1)
+print("Bids:", book.bids)
+print("Asks:", book.asks)
+```
+
+## API Reference
+
+### MersennetProvider
+
+| Method | Description |
+|--------|-------------|
+| `get_block(number, include_txs)` | Get block by number or "latest" |
+| `get_block_by_hash(hash, include_txs)` | Get block by hash |
+| `get_transaction(hash)` | Get transaction by hash |
+| `get_balance(address)` | Get balance (hex string) |
+| `get_nonce(address)` | Get nonce |
+| `send_raw_transaction(raw_tx)` | Send signed transaction |
+| `call(tx_object)` | Simulate call (eth_call) |
+| `chain_id()` | Chain ID |
+| `block_number()` | Latest block number |
+| `view_notes(grant_id_hex, limit, cursor_hex)` | Grant-gated encrypted note export |
+| `gas_price()` | Current gas price |
+
+### MersennetOrders
+
+| Method | Description |
+|--------|-------------|
+| `add_market(base, quote, lot, tick)` | Add market (admin) |
+| `place_order(market, side, price, amount, tif, owner)` | Place order |
+| `cancel_order(order_id)` | Cancel order |
+| `get_order_book(market)` | Get order book |
+| `get_trades(market)` | Get recent trades |
+| `get_positions(address, market)` | Get positions |
+
+### MersennetSubscriber (WebSocket)
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Connect to WebSocket |
+| `disconnect()` | Disconnect |
+| `subscribe_blocks(callback)` | Subscribe to new blocks |
+| `subscribe_trades(market, callback)` | Subscribe to trades |
+| `subscribe_logs(callback, topics, address)` | Subscribe to logs |
+| `unsubscribe(id)` | Unsubscribe |
+
+### Shielded Notes
+
+Use `view_notes` to fetch encrypted note envelopes, then call
+`scan_granted_notes` with a decrypt function that applies your granted
+viewing material locally.
+
+```python
+from mersennet import GrantedViewingMaterial, MersennetProvider, make_mock_note_decryptor, scan_granted_notes
+
+provider = MersennetProvider("http://localhost:8545")
+
+material = GrantedViewingMaterial(
+    grant_id_hex="0x...",
+    recipient_public_key="0x...",
+    decrypt_note_ciphertext=make_mock_note_decryptor("0x..."),
+)
+
+result = scan_granted_notes(provider, material, limit=64)
+print("Decrypted notes:", len(result.notes))
+```
+
+See the runnable end-to-end example in [examples/view_notes_end_to_end.py](examples/view_notes_end_to_end.py).
+
+## WebSocket Example
+
+```python
+from mersennet import MersennetSubscriber
+
+sub = MersennetSubscriber("ws://localhost:8545")
+sub.connect()
+
+def on_block(block):
+    print("New block:", block)
+
+sub_id = sub.subscribe_blocks(on_block)
+# ...
+sub.unsubscribe(sub_id)
+sub.disconnect()
+```
+
+## Error Handling
+
+```python
+from mersennet.provider import MersennetError
+
+try:
+    balance = provider.get_balance("0x...")
+except MersennetError as e:
+    print(f"Error {e.code}: {e}")
+```
+
+---
+
+<p align="center">
+  Part of the <a href="https://github.com/mersennet">Mersennet</a> ecosystem —
+  <a href="https://trade.mersennet.com">trade</a> ·
+  <a href="https://explorer.mersennet.com">explorer</a> ·
+  <a href="https://docs.mersennet.com">docs</a> ·
+  <a href="https://mersennet.com/downloads/">run a node</a> ·
+  <a href="https://t.me/Mersennet">Telegram</a><br>
+  <sub>© 2026 Mersennet Foundation · MIT License · security@mersennet.com</sub>
+</p>

mersennet_sdk-0.1.1/README.md

@@ -0,0 +1,149 @@
+<p align="center"><a href="https://mersennet.com"><img src="https://raw.githubusercontent.com/mersennet/.github/main/profile/mark.svg" width="72" alt="Mersennet"></a></p>
+<h1 align="center">Mersennet Python SDK</h1>
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-7dff9b?style=flat-square" alt="MIT license"></a>
+  <a href="https://github.com/mersennet/sdk-python/actions/workflows/ci.yml"><img src="https://github.com/mersennet/sdk-python/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://docs.mersennet.com/developers/sdks/python/"><img src="https://img.shields.io/badge/docs-mersennet-1c1c1c?style=flat-square" alt="Docs"></a>
+  <a href="https://t.me/Mersennet"><img src="https://img.shields.io/badge/telegram-%40Mersennet-26A5E4?style=flat-square" alt="Telegram"></a>
+</p>
+
+Python client for Mersennet - JSON-RPC, CLOB (order book), and WebSocket subscriptions.
+
+## Installation
+
+```bash
+pip install "git+https://github.com/mersennet/sdk-python.git@v0.1.0"   # PyPI publication pending
+```
+
+Or from source:
+
+```bash
+cd sdk-python
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from mersennet import MersennetProvider, MersennetOrders
+
+provider = MersennetProvider("http://localhost:8545")
+
+# Chain info
+print("Chain ID:", provider.chain_id())
+print("Block:", provider.block_number())
+print("Gas price:", provider.gas_price())
+
+# Account
+balance = provider.get_balance("0xYourAddress")
+print("Balance:", balance)
+
+# Order book
+orders = MersennetOrders(provider)
+book = orders.get_order_book(1)
+print("Bids:", book.bids)
+print("Asks:", book.asks)
+```
+
+## API Reference
+
+### MersennetProvider
+
+| Method | Description |
+|--------|-------------|
+| `get_block(number, include_txs)` | Get block by number or "latest" |
+| `get_block_by_hash(hash, include_txs)` | Get block by hash |
+| `get_transaction(hash)` | Get transaction by hash |
+| `get_balance(address)` | Get balance (hex string) |
+| `get_nonce(address)` | Get nonce |
+| `send_raw_transaction(raw_tx)` | Send signed transaction |
+| `call(tx_object)` | Simulate call (eth_call) |
+| `chain_id()` | Chain ID |
+| `block_number()` | Latest block number |
+| `view_notes(grant_id_hex, limit, cursor_hex)` | Grant-gated encrypted note export |
+| `gas_price()` | Current gas price |
+
+### MersennetOrders
+
+| Method | Description |
+|--------|-------------|
+| `add_market(base, quote, lot, tick)` | Add market (admin) |
+| `place_order(market, side, price, amount, tif, owner)` | Place order |
+| `cancel_order(order_id)` | Cancel order |
+| `get_order_book(market)` | Get order book |
+| `get_trades(market)` | Get recent trades |
+| `get_positions(address, market)` | Get positions |
+
+### MersennetSubscriber (WebSocket)
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Connect to WebSocket |
+| `disconnect()` | Disconnect |
+| `subscribe_blocks(callback)` | Subscribe to new blocks |
+| `subscribe_trades(market, callback)` | Subscribe to trades |
+| `subscribe_logs(callback, topics, address)` | Subscribe to logs |
+| `unsubscribe(id)` | Unsubscribe |
+
+### Shielded Notes
+
+Use `view_notes` to fetch encrypted note envelopes, then call
+`scan_granted_notes` with a decrypt function that applies your granted
+viewing material locally.
+
+```python
+from mersennet import GrantedViewingMaterial, MersennetProvider, make_mock_note_decryptor, scan_granted_notes
+
+provider = MersennetProvider("http://localhost:8545")
+
+material = GrantedViewingMaterial(
+    grant_id_hex="0x...",
+    recipient_public_key="0x...",
+    decrypt_note_ciphertext=make_mock_note_decryptor("0x..."),
+)
+
+result = scan_granted_notes(provider, material, limit=64)
+print("Decrypted notes:", len(result.notes))
+```
+
+See the runnable end-to-end example in [examples/view_notes_end_to_end.py](examples/view_notes_end_to_end.py).
+
+## WebSocket Example
+
+```python
+from mersennet import MersennetSubscriber
+
+sub = MersennetSubscriber("ws://localhost:8545")
+sub.connect()
+
+def on_block(block):
+    print("New block:", block)
+
+sub_id = sub.subscribe_blocks(on_block)
+# ...
+sub.unsubscribe(sub_id)
+sub.disconnect()
+```
+
+## Error Handling
+
+```python
+from mersennet.provider import MersennetError
+
+try:
+    balance = provider.get_balance("0x...")
+except MersennetError as e:
+    print(f"Error {e.code}: {e}")
+```
+
+---
+
+<p align="center">
+  Part of the <a href="https://github.com/mersennet">Mersennet</a> ecosystem —
+  <a href="https://trade.mersennet.com">trade</a> ·
+  <a href="https://explorer.mersennet.com">explorer</a> ·
+  <a href="https://docs.mersennet.com">docs</a> ·
+  <a href="https://mersennet.com/downloads/">run a node</a> ·
+  <a href="https://t.me/Mersennet">Telegram</a><br>
+  <sub>© 2026 Mersennet Foundation · MIT License · security@mersennet.com</sub>
+</p>

mersennet_sdk-0.1.1/mersennet/__init__.py

@@ -0,0 +1,83 @@
+"""Mersennet Python SDK - JSON-RPC, CLOB, shielded privacy, and WebSocket client."""
+
+__version__ = "0.1.1"
+
+from .provider import MersennetProvider
+from .orders import MersennetOrders
+from .shielded import (
+	EncryptedNoteEnvelope,
+	GrantedDecryptedNote,
+	GrantedNoteDecryptInput,
+	GrantedNoteScanResult,
+	GrantedViewingMaterial,
+	ShieldedNote,
+	ViewingKey,
+	create_owner_viewing_material,
+	delegate_view_token,
+	make_mock_note_decryptor,
+	parse_encrypted_note_payload,
+	parse_shielded_note_plaintext,
+	scan_granted_notes,
+	viewing_key_from_seed,
+)
+from .reconstruction import (
+	BalanceReconstructionResult,
+	PortfolioNote,
+	ReconstructedPortfolio,
+	default_nullifier_deriver,
+	reconstruct_portfolio,
+	scan_and_reconstruct_balances,
+)
+from .positions import (
+	FillRecord,
+	OpenOrder,
+	OrderRecord,
+	ReconstructedPosition,
+	reconstruct_open_orders,
+	reconstruct_positions,
+)
+from .attestation import (
+	ComplianceAttestation,
+	build_portfolio_attestation,
+	verify_attestation,
+)
+from .subscriber import MersennetSubscriber
+
+__all__ = [
+	"MersennetProvider",
+	"MersennetOrders",
+	"MersennetSubscriber",
+	# shielded note scanning + viewing keys
+	"EncryptedNoteEnvelope",
+	"GrantedDecryptedNote",
+	"GrantedNoteDecryptInput",
+	"GrantedNoteScanResult",
+	"GrantedViewingMaterial",
+	"ShieldedNote",
+	"ViewingKey",
+	"create_owner_viewing_material",
+	"delegate_view_token",
+	"make_mock_note_decryptor",
+	"parse_encrypted_note_payload",
+	"parse_shielded_note_plaintext",
+	"scan_granted_notes",
+	"viewing_key_from_seed",
+	# balance reconstruction
+	"BalanceReconstructionResult",
+	"PortfolioNote",
+	"ReconstructedPortfolio",
+	"default_nullifier_deriver",
+	"reconstruct_portfolio",
+	"scan_and_reconstruct_balances",
+	# order/position reconstruction
+	"FillRecord",
+	"OpenOrder",
+	"OrderRecord",
+	"ReconstructedPosition",
+	"reconstruct_open_orders",
+	"reconstruct_positions",
+	# compliance attestation
+	"ComplianceAttestation",
+	"build_portfolio_attestation",
+	"verify_attestation",
+]

mersennet_sdk-0.1.1/mersennet/attestation.py

@@ -0,0 +1,236 @@
+"""Compliance / view-key attestation (selective disclosure, ADR-019).
+
+A grantee holding a scoped viewing grant (e.g. an exchange, auditor, or
+regulated counterparty) reconstructs a grantor's shielded portfolio locally
+and then produces a **portable, tamper-evident attestation**: a compact
+document asserting the balances observed as of a specific block and shielded
+state root, bound to the grant.
+
+The attestation is the selective-disclosure output: the grantor reveals
+exactly the scope the grant permits, to exactly the party the grant names,
+and the recipient can hand the signed artifact to a third party (an auditor,
+a compliance desk) who can verify integrity without any chain access.
+
+Design goals:
+  * **Deterministic digest** - a canonical serialization hashed with SHA-256,
+    so the same portfolio always yields the same digest across SDKs.
+  * **Cross-checkable** - carries the node's ``mersennet_viewPortfolioDigest``
+    when available, and flags whether the locally-reconstructed digest matches.
+  * **Dependency-free signing** - signing/verification are injected callbacks,
+    so a wallet can plug in secp256k1/ed25519 without the SDK forcing a dep.
+
+This is a faithful cross-language design shared with the TypeScript and Go
+SDKs (``attestation.ts`` / ``attestation.go``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import hashlib
+import time
+from typing import Callable, Dict, Optional, Tuple
+
+from .reconstruction import BalanceReconstructionResult, ReconstructedPortfolio
+
+ATTESTATION_VERSION = "mersennet-attestation-v1"
+
+# Signer: (digest_hex) -> signature_hex.  Verifier: (digest_hex, signature_hex, attester) -> bool.
+Signer = Callable[[str], str]
+Verifier = Callable[[str, str, Optional[str]], bool]
+
+
+@dataclass
+class ComplianceAttestation:
+    version: str
+    grant_id: str
+    grantor_commitment: str
+    block_number: int
+    shielded_state_root: str
+    per_asset: Dict[int, int]
+    unspent_note_count: int
+    spent_nullifier_count: int
+    portfolio_digest: str
+    issued_at: int
+    scope: str = "balances:read"
+    onchain_portfolio_digest: Optional[str] = None
+    digest_matches_onchain: Optional[bool] = None
+    attester: Optional[str] = None
+    signature: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        """JSON-serializable dict with camelCase keys (wire parity with TS/Go)."""
+        return {
+            "version": self.version,
+            "grantId": self.grant_id,
+            "grantorCommitment": self.grantor_commitment,
+            "blockNumber": self.block_number,
+            "shieldedStateRoot": self.shielded_state_root,
+            "perAsset": {str(k): str(v) for k, v in sorted(self.per_asset.items())},
+            "unspentNoteCount": self.unspent_note_count,
+            "spentNullifierCount": self.spent_nullifier_count,
+            "portfolioDigest": self.portfolio_digest,
+            "issuedAt": self.issued_at,
+            "scope": self.scope,
+            "onchainPortfolioDigest": self.onchain_portfolio_digest,
+            "digestMatchesOnchain": self.digest_matches_onchain,
+            "attester": self.attester,
+            "signature": self.signature,
+        }
+
+    @staticmethod
+    def from_dict(obj: Dict) -> "ComplianceAttestation":
+        per_asset = {int(k): int(v) for k, v in (obj.get("perAsset", {}) or {}).items()}
+        return ComplianceAttestation(
+            version=obj.get("version", ATTESTATION_VERSION),
+            grant_id=obj.get("grantId", "0x"),
+            grantor_commitment=obj.get("grantorCommitment", "0x"),
+            block_number=obj.get("blockNumber", 0),
+            shielded_state_root=obj.get("shieldedStateRoot", "0x"),
+            per_asset=per_asset,
+            unspent_note_count=obj.get("unspentNoteCount", 0),
+            spent_nullifier_count=obj.get("spentNullifierCount", 0),
+            portfolio_digest=obj.get("portfolioDigest", "0x"),
+            issued_at=obj.get("issuedAt", 0),
+            scope=obj.get("scope", "balances:read"),
+            onchain_portfolio_digest=obj.get("onchainPortfolioDigest"),
+            digest_matches_onchain=obj.get("digestMatchesOnchain"),
+            attester=obj.get("attester"),
+            signature=obj.get("signature"),
+        )
+
+
+def _canonical_preimage(
+    grant_id: str,
+    grantor_commitment: str,
+    block_number: int,
+    shielded_state_root: str,
+    per_asset: Dict[int, int],
+    unspent_note_count: int,
+    spent_nullifier_count: int,
+) -> str:
+    """Deterministic string over the disclosed facts. Asset ids are sorted so
+    dict ordering never affects the digest; this string is identical across
+    the TS/Python/Go SDKs."""
+    assets = "|".join(f"{aid}:{per_asset[aid]}" for aid in sorted(per_asset))
+    return "\n".join(
+        [
+            ATTESTATION_VERSION,
+            grant_id.lower(),
+            grantor_commitment.lower(),
+            str(block_number),
+            shielded_state_root.lower(),
+            assets,
+            str(unspent_note_count),
+            str(spent_nullifier_count),
+        ]
+    )
+
+
+def compute_portfolio_digest(
+    grant_id: str,
+    grantor_commitment: str,
+    block_number: int,
+    shielded_state_root: str,
+    per_asset: Dict[int, int],
+    unspent_note_count: int,
+    spent_nullifier_count: int,
+) -> str:
+    preimage = _canonical_preimage(
+        grant_id,
+        grantor_commitment,
+        block_number,
+        shielded_state_root,
+        per_asset,
+        unspent_note_count,
+        spent_nullifier_count,
+    )
+    return "0x" + hashlib.sha256(preimage.encode("utf-8")).hexdigest()
+
+
+def build_portfolio_attestation(
+    result: BalanceReconstructionResult,
+    *,
+    grantor_commitment: str = "0x",
+    scope: str = "balances:read",
+    onchain_portfolio_digest: Optional[str] = None,
+    attester: Optional[str] = None,
+    sign: Optional[Signer] = None,
+    issued_at: Optional[int] = None,
+) -> ComplianceAttestation:
+    """Build a compliance attestation from a reconstructed balance result.
+
+    ``result`` typically comes from :func:`scan_and_reconstruct_balances`.
+    Pass ``onchain_portfolio_digest`` (from
+    ``provider`` ``mersennet_viewPortfolioDigest``) to cross-check the local
+    reconstruction against the node's independent digest. Pass a ``sign``
+    callback to bind the attester's signature over the portfolio digest.
+    """
+    digest = compute_portfolio_digest(
+        result.grant_id,
+        grantor_commitment,
+        result.block_number,
+        result.shielded_state_root,
+        result.per_asset,
+        result.unspent_note_count,
+        result.spent_nullifier_count,
+    )
+
+    digest_matches: Optional[bool] = None
+    if onchain_portfolio_digest is not None:
+        digest_matches = onchain_portfolio_digest.lower() == digest.lower()
+
+    signature = sign(digest) if sign is not None else None
+
+    return ComplianceAttestation(
+        version=ATTESTATION_VERSION,
+        grant_id=result.grant_id,
+        grantor_commitment=grantor_commitment,
+        block_number=result.block_number,
+        shielded_state_root=result.shielded_state_root,
+        per_asset=dict(result.per_asset),
+        unspent_note_count=result.unspent_note_count,
+        spent_nullifier_count=result.spent_nullifier_count,
+        portfolio_digest=digest,
+        issued_at=issued_at if issued_at is not None else int(time.time()),
+        scope=scope,
+        onchain_portfolio_digest=onchain_portfolio_digest,
+        digest_matches_onchain=digest_matches,
+        attester=attester,
+        signature=signature,
+    )
+
+
+def verify_attestation(
+    attestation: ComplianceAttestation,
+    *,
+    verify_sig: Optional[Verifier] = None,
+) -> Tuple[bool, str]:
+    """Verify an attestation's integrity (and optionally its signature).
+
+    Returns ``(ok, reason)``. Integrity: recompute the digest from the
+    attestation's own disclosed fields and require it to equal the embedded
+    ``portfolio_digest``. If ``verify_sig`` is supplied and a signature is
+    present, the signature must also verify over the digest.
+    """
+    recomputed = compute_portfolio_digest(
+        attestation.grant_id,
+        attestation.grantor_commitment,
+        attestation.block_number,
+        attestation.shielded_state_root,
+        attestation.per_asset,
+        attestation.unspent_note_count,
+        attestation.spent_nullifier_count,
+    )
+    if recomputed.lower() != attestation.portfolio_digest.lower():
+        return False, "digest mismatch: attestation fields do not hash to the embedded digest"
+
+    if attestation.digest_matches_onchain is False:
+        return False, "reconstructed digest did not match the on-chain portfolio digest"
+
+    if verify_sig is not None:
+        if not attestation.signature:
+            return False, "signature required but missing"
+        if not verify_sig(attestation.portfolio_digest, attestation.signature, attestation.attester):
+            return False, "signature verification failed"
+
+    return True, "ok"