feat(wasm-sdk)!: add shielded pool WASM bindings and query methods

.gitignore

@@ -8,6 +8,9 @@
 # ignore VSCode project specific files
 .vscode
 
+# ignore Serena MCP project-local cache/config
+.serena
+
 # Env file
 .env
 

packages/js-evo-sdk/src/sdk.ts

@@ -12,6 +12,7 @@ import { StateTransitionsFacade } from './state-transitions/facade.js';
 import { SystemFacade } from './system/facade.js';
 import { GroupFacade } from './group/facade.js';
 import { VotingFacade } from './voting/facade.js';
+import { ShieldedFacade } from './shielded/facade.js';
 
 export interface ConnectionOptions {
   version?: number;
@@ -52,6 +53,7 @@ export class EvoSDK {
   public system!: SystemFacade;
   public group!: GroupFacade;
   public voting!: VotingFacade;
+  public shielded!: ShieldedFacade;
   constructor(options: EvoSDKOptions = {}) {
     // Apply defaults while preserving any future connection options
     const { network = 'testnet', trusted = false, addresses, ...connection } = options;
@@ -69,6 +71,7 @@ export class EvoSDK {
     this.system = new SystemFacade(this);
     this.group = new GroupFacade(this);
     this.voting = new VotingFacade(this);
+    this.shielded = new ShieldedFacade(this);
   }
 
   get wasm(): wasm.WasmSdk {
@@ -209,5 +212,6 @@ export { StateTransitionsFacade } from './state-transitions/facade.js';
 export { SystemFacade } from './system/facade.js';
 export { GroupFacade } from './group/facade.js';
 export { VotingFacade } from './voting/facade.js';
+export { ShieldedFacade } from './shielded/facade.js';
 export { wallet } from './wallet/functions.js';
 export * from './wasm.js';

packages/js-evo-sdk/src/shielded/facade.ts

@@ -0,0 +1,86 @@
+import * as wasm from '../wasm.js';
+import type { EvoSDK } from '../sdk.js';
+
+/**
+ * Read-only access to the shielded (Orchard) pool: total balance, encrypted
+ * notes, anchors, nullifier statuses. Each query has a `*WithProof` variant
+ * that additionally returns proof + metadata for cryptographic verification.
+ *
+ * Building / signing / broadcasting shielded transitions is intentionally
+ * out of scope here — that requires the Orchard prover and is tracked
+ * separately. See PR #3235 for the deferral rationale.
+ */
+export class ShieldedFacade {
+  private sdk: EvoSDK;
+
+  constructor(sdk: EvoSDK) {
+    this.sdk = sdk;
+  }
+
+  // ── Pool state ────────────────────────────────────────────────────────
+
+  async poolState(): Promise<bigint | undefined> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getShieldedPoolState();
+  }
+
+  async poolStateWithProof(): Promise<wasm.ProofMetadataResponseTyped<bigint | null>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getShieldedPoolStateWithProofInfo();
+  }
+
+  // ── Encrypted notes ──────────────────────────────────────────────────
+
+  async encryptedNotes(startIndex: bigint, count: number): Promise<wasm.ShieldedEncryptedNote[]> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getShieldedEncryptedNotes(startIndex, count);
+  }
+
+  async encryptedNotesWithProof(
+    startIndex: bigint,
+    count: number,
+  ): Promise<wasm.ProofMetadataResponseTyped<wasm.ShieldedEncryptedNote[]>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getShieldedEncryptedNotesWithProofInfo(startIndex, count);
+  }
+
+  // ── Anchors ──────────────────────────────────────────────────────────
+
+  async anchors(): Promise<Uint8Array[]> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getShieldedAnchors();
+  }
+
+  async anchorsWithProof(): Promise<wasm.ProofMetadataResponseTyped<Uint8Array[]>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getShieldedAnchorsWithProofInfo();
+  }
+
+  async mostRecentAnchor(): Promise<Uint8Array | undefined> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getMostRecentShieldedAnchor();
+  }
+
+  async mostRecentAnchorWithProof(): Promise<wasm.ProofMetadataResponseTyped<Uint8Array | null>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getMostRecentShieldedAnchorWithProofInfo();
+  }
+
+  // ── Nullifiers ───────────────────────────────────────────────────────
+
+  /**
+   * Each nullifier must be a `Uint8Array` of exactly 32 bytes; otherwise
+   * the underlying call rejects with `InvalidArgument`.
+   */
+  async nullifiers(nullifiers: Uint8Array[]): Promise<wasm.ShieldedNullifierStatus[]> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getShieldedNullifiers(nullifiers);
+  }
+
+  async nullifiersWithProof(
+    nullifiers: Uint8Array[],
+  ): Promise<wasm.ProofMetadataResponseTyped<wasm.ShieldedNullifierStatus[]>> {
+    const w = await this.sdk.getWasmSdkConnected();
+    return w.getShieldedNullifiersWithProofInfo(nullifiers);
+  }
+}

packages/js-evo-sdk/tests/unit/facades/shielded.spec.ts

@@ -0,0 +1,121 @@
+import type { SinonStub } from 'sinon';
+import init, * as wasmSDKPackage from '@dashevo/wasm-sdk';
+import { EvoSDK } from '../../../dist/sdk.js';
+
+describe('ShieldedFacade', () => {
+  let wasmSdk: wasmSDKPackage.WasmSdk;
+  let client: EvoSDK;
+
+  let getShieldedPoolStateStub: SinonStub;
+  let getShieldedPoolStateWithProofInfoStub: SinonStub;
+  let getShieldedEncryptedNotesStub: SinonStub;
+  let getShieldedEncryptedNotesWithProofInfoStub: SinonStub;
+  let getShieldedAnchorsStub: SinonStub;
+  let getShieldedAnchorsWithProofInfoStub: SinonStub;
+  let getMostRecentShieldedAnchorStub: SinonStub;
+  let getMostRecentShieldedAnchorWithProofInfoStub: SinonStub;
+  let getShieldedNullifiersStub: SinonStub;
+  let getShieldedNullifiersWithProofInfoStub: SinonStub;
+
+  beforeEach(async function setup() {
+    await init();
+    const builder = wasmSDKPackage.WasmSdkBuilder.testnet();
+    wasmSdk = await builder.build();
+    client = EvoSDK.fromWasm(wasmSdk);
+
+    getShieldedPoolStateStub = this.sinon.stub(wasmSdk, 'getShieldedPoolState').resolves(1000n);
+    getShieldedPoolStateWithProofInfoStub = this.sinon.stub(wasmSdk, 'getShieldedPoolStateWithProofInfo').resolves('proof');
+    getShieldedEncryptedNotesStub = this.sinon.stub(wasmSdk, 'getShieldedEncryptedNotes').resolves([]);
+    getShieldedEncryptedNotesWithProofInfoStub = this.sinon.stub(wasmSdk, 'getShieldedEncryptedNotesWithProofInfo').resolves('proof');
+    getShieldedAnchorsStub = this.sinon.stub(wasmSdk, 'getShieldedAnchors').resolves([]);
+    getShieldedAnchorsWithProofInfoStub = this.sinon.stub(wasmSdk, 'getShieldedAnchorsWithProofInfo').resolves('proof');
+    getMostRecentShieldedAnchorStub = this.sinon.stub(wasmSdk, 'getMostRecentShieldedAnchor').resolves(undefined);
+    getMostRecentShieldedAnchorWithProofInfoStub = this.sinon.stub(wasmSdk, 'getMostRecentShieldedAnchorWithProofInfo').resolves('proof');
+    getShieldedNullifiersStub = this.sinon.stub(wasmSdk, 'getShieldedNullifiers').resolves([]);
+    getShieldedNullifiersWithProofInfoStub = this.sinon.stub(wasmSdk, 'getShieldedNullifiersWithProofInfo').resolves('proof');
+  });
+
+  describe('poolState()', () => {
+    it('should forward to getShieldedPoolState and return its result', async () => {
+      const result = await client.shielded.poolState();
+      expect(getShieldedPoolStateStub).to.be.calledOnce();
+      expect(result).to.equal(1000n);
+    });
+  });
+
+  describe('poolStateWithProof()', () => {
+    it('should forward to getShieldedPoolStateWithProofInfo', async () => {
+      await client.shielded.poolStateWithProof();
+      expect(getShieldedPoolStateWithProofInfoStub).to.be.calledOnce();
+    });
+  });
+
+  describe('encryptedNotes()', () => {
+    it('should forward startIndex/count to getShieldedEncryptedNotes', async () => {
+      await client.shielded.encryptedNotes(0n, 10);
+      expect(getShieldedEncryptedNotesStub).to.be.calledOnceWithExactly(0n, 10);
+    });
+
+    it('should pass through bigint startIndex without truncation', async () => {
+      const big = 9_007_199_254_740_993n; // > Number.MAX_SAFE_INTEGER
+      await client.shielded.encryptedNotes(big, 5);
+      expect(getShieldedEncryptedNotesStub).to.be.calledWith(big, 5);
+    });
+  });
+
+  describe('encryptedNotesWithProof()', () => {
+    it('should forward startIndex/count to getShieldedEncryptedNotesWithProofInfo', async () => {
+      await client.shielded.encryptedNotesWithProof(100n, 25);
+      expect(getShieldedEncryptedNotesWithProofInfoStub).to.be.calledOnceWithExactly(100n, 25);
+    });
+  });
+
+  describe('anchors()', () => {
+    it('should forward to getShieldedAnchors', async () => {
+      await client.shielded.anchors();
+      expect(getShieldedAnchorsStub).to.be.calledOnce();
+    });
+  });
+
+  describe('anchorsWithProof()', () => {
+    it('should forward to getShieldedAnchorsWithProofInfo', async () => {
+      await client.shielded.anchorsWithProof();
+      expect(getShieldedAnchorsWithProofInfoStub).to.be.calledOnce();
+    });
+  });
+
+  describe('mostRecentAnchor()', () => {
+    it('should forward to getMostRecentShieldedAnchor', async () => {
+      await client.shielded.mostRecentAnchor();
+      expect(getMostRecentShieldedAnchorStub).to.be.calledOnce();
+    });
+  });
+
+  describe('mostRecentAnchorWithProof()', () => {
+    it('should forward to getMostRecentShieldedAnchorWithProofInfo', async () => {
+      await client.shielded.mostRecentAnchorWithProof();
+      expect(getMostRecentShieldedAnchorWithProofInfoStub).to.be.calledOnce();
+    });
+  });
+
+  describe('nullifiers()', () => {
+    it('should forward the nullifier array to getShieldedNullifiers', async () => {
+      const nullifiers = [new Uint8Array(32).fill(1), new Uint8Array(32).fill(2)];
+      await client.shielded.nullifiers(nullifiers);
+      expect(getShieldedNullifiersStub).to.be.calledOnceWithExactly(nullifiers);
+    });
+
+    it('should accept an empty array', async () => {
+      await client.shielded.nullifiers([]);
+      expect(getShieldedNullifiersStub).to.be.calledOnceWithExactly([]);
+    });
+  });
+
+  describe('nullifiersWithProof()', () => {
+    it('should forward the nullifier array to getShieldedNullifiersWithProofInfo', async () => {
+      const nullifiers = [new Uint8Array(32).fill(7)];
+      await client.shielded.nullifiersWithProof(nullifiers);
+      expect(getShieldedNullifiersWithProofInfoStub).to.be.calledOnceWithExactly(nullifiers);
+    });
+  });
+});

packages/rs-dpp-json-convertible-derive/src/lib.rs

@@ -7,25 +7,50 @@ use syn::{parse_macro_input, Data, DeriveInput, Fields, Ident, Item, Type};
 
 const DEFAULT_BASE_PATH: &str = "crate::serialization";
 
-/// Attribute macro that adds `#[serde(with = "...")]` to `u64`/`i64` fields
-/// and implements `JsonSafeFields` for the type (when used inside the `dpp` crate).
+/// Attribute macro that auto-injects `#[serde(with = "...")]` on fields whose
+/// natural serde shape would round-trip badly through JSON / WASM.
 ///
 /// Works on both **structs** and **enums** (with named fields in variants).
 ///
-/// Matches literal `u64`, `i64`, `Option<u64>`, `Option<i64>`, and known type aliases
-/// (e.g. `Credits`, `TokenAmount`, `TimestampMillis`, `BlockHeight`).
-/// The macro skips fields that already have `#[serde(with)]`.
+/// # What it injects
+///
+/// | Field type | Helper injected | Wire shape |
+/// |---|---|---|
+/// | `u64` / `Option<u64>` and known aliases (`Credits`, `TokenAmount`, `TimestampMillis`, `BlockHeight`, …) | `json_safe_u64` / `json_safe_option_u64` | number ≤ `MAX_SAFE_INTEGER`, otherwise string — avoids JS precision loss |
+/// | `i64` / `Option<i64>` and known aliases | `json_safe_i64` / `json_safe_option_i64` | same, signed |
+/// | `[u8; N]` (any `N`, via const generics) | `serde_bytes` | raw bytes in binary, base64 string in JSON |
+/// | `Vec<u8>` | `serde_bytes_var` | raw bytes in binary, base64 string in JSON |
+///
+/// The byte-field handling matches the broader codebase convention used by
+/// `Bytes20` / `Bytes32` / `Bytes36` / `BinaryData` in `rs-platform-value`.
+///
+/// Fields that already carry an explicit `#[serde(with = "…")]` (or
+/// `skip` / `flatten` / `cfg_attr` wrapping a `serde(with)`) are left
+/// untouched.
+///
+/// # Compile-time transitive guarantee
+///
+/// When applied inside the `dpp` crate, the macro also implements the marker
+/// trait `JsonSafeFields` for the type, and emits compile-time assertions that
+/// every nested non-primitive field type (anything not directly handled above)
+/// also implements `JsonSafeFields`. This propagates the safety check
+/// transitively — adding a new struct that contains a `Credits` without an
+/// `#[json_safe_fields]` annotation will fail to compile.
+///
+/// # Feature flags
 ///
 /// When serde derives are behind `cfg_attr(feature = "...")`, the `cfg_attr` is
-/// evaluated by the compiler BEFORE this macro runs. If the feature is off, serde
-/// derives aren't visible and `#[serde(with)]` is NOT generated — which is correct
-/// because `serde(with)` requires an active serde derive.
+/// evaluated by the compiler BEFORE this macro runs. If the feature is off,
+/// serde derives aren't visible and `#[serde(with)]` is NOT generated — which
+/// is correct because `serde(with)` requires an active serde derive.
 ///
 /// # Inside `dpp` crate (default)
 /// ```ignore
 /// #[json_safe_fields]
 /// pub struct MyStructV0 {
 ///     pub supply: u64,          // → auto-annotated with crate::serialization::json_safe_u64
+///     pub anchor: [u8; 32],     // → auto-annotated with crate::serialization::serde_bytes
+///     pub proof: Vec<u8>,       // → auto-annotated with crate::serialization::serde_bytes_var
 ///     pub name: String,         // → untouched
 /// }
 /// ```
@@ -290,12 +315,18 @@ fn annotate_fields(fields: &mut syn::FieldsNamed, base_path: &str) -> Vec<Type>
 
 /// Determine if a type needs a serde `with` annotation and return the module name suffix.
 ///
-/// Matches literal `u64`, `i64`, `Option<u64>`, `Option<i64>`, and known type aliases
-/// that resolve to u64/i64 (e.g. `Credits`, `TokenAmount`, `TimestampMillis`).
+/// Matches:
+/// - `u64`, `i64`, `Option<u64>`, `Option<i64>`, and known u64/i64 type aliases
+///   (e.g. `Credits`, `TokenAmount`, `TimestampMillis`) → `json_safe_*` helpers
+/// - `[u8; N]` for any `N` → `serde_bytes` (const-generic; raw bytes in binary,
+///   base64 string in JSON)
+/// - `Vec<u8>` → `serde_bytes_var` (variable-length variant of the above)
 ///
 /// When adding a new `type X = u64` alias in rs-dpp, add it to the appropriate list below.
 fn serde_with_suffix_for_type(ty: &Type) -> Option<&'static str> {
     match ty {
+        // [u8; N] — any fixed-size byte array, length-agnostic via const generics.
+        Type::Array(arr) if is_u8_type(&arr.elem) => Some("serde_bytes"),
         Type::Path(type_path) => {
             let segments = &type_path.path.segments;
             // Get the last segment — handles both `u64` and `std::u64` / `crate::prelude::Credits`
@@ -308,6 +339,18 @@ fn serde_with_suffix_for_type(ty: &Type) -> Option<&'static str> {
             if is_i64_type(ident) {
                 return Some("json_safe_i64");
             }
+            // Vec<u8> → variable-length bytes helper (base64 in JSON, raw in binary).
+            if ident == "Vec" {
+                if let syn::PathArguments::AngleBracketed(args) = &last.arguments {
+                    if args.args.len() == 1 {
+                        if let syn::GenericArgument::Type(inner_ty) = &args.args[0] {
+                            if is_u8_type(inner_ty) {
+                                return Some("serde_bytes_var");
+                            }
+                        }
+                    }
+                }
+            }
             // Check for Option<u64/i64/alias> — handles both `Option<T>` and `std::option::Option<T>`
             if ident == "Option" {
                 if let syn::PathArguments::AngleBracketed(args) = &last.arguments {
@@ -431,6 +474,17 @@ fn is_i64_type(ident: &Ident) -> bool {
     ident == "i64" || I64_ALIASES.iter().any(|alias| ident == alias)
 }
 
+/// True when the type resolves to `u8` — used to detect `[u8; N]` and `Vec<u8>`
+/// byte fields and auto-inject the matching `serde_bytes_*` helper.
+fn is_u8_type(ty: &Type) -> bool {
+    if let Type::Path(type_path) = ty {
+        if let Some(last) = type_path.path.segments.last() {
+            return last.ident == "u8" && last.arguments.is_empty();
+        }
+    }
+    false
+}
+
 /// Derive macro that generates `impl JsonConvertible for Type {}` with
 /// compile-time assertions that all inner types implement `JsonSafeFields`.
 ///