dash-platform-sdk 1.4.0 → 1.5.0-dev.1

package/src/DashPlatformSDK.d.ts

@@ -12,6 +12,7 @@ import { TokensController } from './tokens/index.js';
 import { VotingController } from './voting/index.js';
 import { Network } from '../types.js';
 import { PlatformAddressesController } from './platformAddresses/index.js';
+import { ShieldedController } from './shielded/index.js';
 export interface GRPCOptions {
     poolLimit: 5;
     dapiUrl?: string | string[];
@@ -33,6 +34,7 @@ export declare class DashPlatformSDK {
     options?: SDKOptions;
     contestedResources: ContestedResourcesController;
     platformAddresses: PlatformAddressesController;
+    shielded: ShieldedController;
     stateTransitions: StateTransitionsController;
     dataContracts: DataContractsController;
     identities: IdentitiesController;

package/src/DashPlatformSDK.js

@@ -11,6 +11,7 @@ import { ContestedResourcesController } from './contestedResources/index.js';
 import { TokensController } from './tokens/index.js';
 import { VotingController } from './voting/index.js';
 import { PlatformAddressesController } from './platformAddresses/index.js';
+import { ShieldedController } from './shielded/index.js';
 /**
  * Javascript SDK for that let you interact with a Dash Platform blockchain
  */
@@ -22,6 +23,7 @@ export class DashPlatformSDK {
     options;
     contestedResources;
     platformAddresses;
+    shielded;
     stateTransitions;
     dataContracts;
     identities;
@@ -65,6 +67,7 @@ export class DashPlatformSDK {
         this.grpcPool = grpcPool;
         this.contestedResources = new ContestedResourcesController(grpcPool);
         this.platformAddresses = new PlatformAddressesController(grpcPool);
+        this.shielded = new ShieldedController(grpcPool);
         this.stateTransitions = new StateTransitionsController(grpcPool);
         this.dataContracts = new DataContractsController(grpcPool);
         this.identities = new IdentitiesController(grpcPool);

package/src/constants.d.ts

@@ -3,6 +3,7 @@ import { PlatformVersionWASM } from 'pshenmic-dpp';
  * Default amount of documents to retrieve from DAPI
  */
 export declare const DAPI_DEFAULT_LIMIT = 100;
+export declare const SHIELDED_MAX_NOTES_PER_QUERY = 8192;
 export declare const HALVING_INTERVAL = 210240;
 export declare const TESTNET_ACTIVATION_HEIGHT = 1066900;
 export declare const MAINNET_ACTIVATION_HEIGHT = 2128896;

package/src/constants.js

@@ -3,6 +3,7 @@ import { PlatformVersionWASM } from 'pshenmic-dpp';
  * Default amount of documents to retrieve from DAPI
  */
 export const DAPI_DEFAULT_LIMIT = 100;
+export const SHIELDED_MAX_NOTES_PER_QUERY = 8192;
 export const HALVING_INTERVAL = 210240;
 export const TESTNET_ACTIVATION_HEIGHT = 1066900;
 export const MAINNET_ACTIVATION_HEIGHT = 2128896;

package/src/keyPair/index.d.ts

@@ -1,5 +1,6 @@
 import { HDKey } from '@scure/bip32';
 import { Network } from '../../types.js';
+import { OrchardAddressWASM } from 'pshenmic-dpp';
 /**
  * Collection of functions to work with private keys and seed phrases
  *
@@ -64,4 +65,28 @@ export declare class KeyPairController {
      * @returns {string}
      */
     p2pkhAddress(publicKey: Uint8Array, network: Network): string;
+    /**
+     * Derives a shielded (Orchard) address from a BIP-39 seed via ZIP-32
+     * (m/32'/coinType'/account').
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - ZIP-32 account index
+     * @param diversifierIndex {number=} - optional diversifier index
+     *
+     * @returns {OrchardAddressWASM}
+     */
+    deriveShieldedAddress(seed: Uint8Array, network: Network, account: number, diversifierIndex?: number): OrchardAddressWASM;
+    /**
+     * Derives the sender's Orchard outgoing viewing key (OVK, 32 bytes) from a
+     * BIP-39 seed via ZIP-32 (m/32'/coinType'/account'). Used to recover the
+     * outgoing notes a wallet sent.
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - ZIP-32 account index
+     *
+     * @returns {Uint8Array} 32-byte outgoing viewing key
+     */
+    deriveShieldedOutgoingViewingKey(seed: Uint8Array, network: Network, account: number): Uint8Array;
 }

package/src/keyPair/index.js

@@ -3,6 +3,7 @@ import mnemonicToSeed from './mnemonicToSeed.js';
 import deriveChild from './deriveChild.js';
 import derivePath from './derivePath.js';
 import { p2pkh } from '@scure/btc-signer';
+import { OrchardAddressWASM, orchardOvkFromSeed } from 'pshenmic-dpp';
 const DASH_VERSIONS = {
     mainnet: { pubKeyHash: 0x4c, scriptHash: 0x10, bech32: 'dc', wif: 0xcc, private: 0x0488ade4, public: 0x0488b21e },
     testnet: { pubKeyHash: 0x8c, scriptHash: 0x13, bech32: 'dc', wif: 0xef, private: 0x04358394, public: 0x043587cf }
@@ -86,4 +87,36 @@ export class KeyPairController {
         const P2PKH = p2pkh(publicKey, DASH_VERSIONS[network]);
         return P2PKH.address;
     }
+    /**
+     * Derives a shielded (Orchard) address from a BIP-39 seed via ZIP-32
+     * (m/32'/coinType'/account').
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - ZIP-32 account index
+     * @param diversifierIndex {number=} - optional diversifier index
+     *
+     * @returns {OrchardAddressWASM}
+     */
+    deriveShieldedAddress(seed, network, account, diversifierIndex) {
+        // SLIP-44 coin type: 5 = Dash mainnet, 1 = testnets. Orchard derives via ZIP-32
+        const coinType = network === 'mainnet' ? 5 : 1;
+        return OrchardAddressWASM.fromSeed(seed, coinType, account, diversifierIndex);
+    }
+    /**
+     * Derives the sender's Orchard outgoing viewing key (OVK, 32 bytes) from a
+     * BIP-39 seed via ZIP-32 (m/32'/coinType'/account'). Used to recover the
+     * outgoing notes a wallet sent.
+     *
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param network {Network} - network (selects the SLIP-44 coin type)
+     * @param account {number} - ZIP-32 account index
+     *
+     * @returns {Uint8Array} 32-byte outgoing viewing key
+     */
+    deriveShieldedOutgoingViewingKey(seed, network, account) {
+        // SLIP-44 coin type: 5 = Dash mainnet, 1 = testnets. Orchard derives via ZIP-32
+        const coinType = network === 'mainnet' ? 5 : 1;
+        return orchardOvkFromSeed(seed, coinType, account);
+    }
 }

package/src/shielded/createStateTransition.d.ts

@@ -0,0 +1,3 @@
+import { ShieldedBuilderWASM, StateTransitionWASM } from 'pshenmic-dpp';
+import { ShieldedTransitionParamsMap, ShieldedTransitionType } from '../../types.js';
+export default function createStateTransition<K extends ShieldedTransitionType>(builder: ShieldedBuilderWASM, type: K, params: ShieldedTransitionParamsMap[K]): StateTransitionWASM;

package/src/shielded/createStateTransition.js

@@ -0,0 +1,55 @@
+import { IdentityCreateFromShieldedPoolTransitionWASM, ShieldedBuilderWASM, ShieldedWithdrawalResultWASM, StateTransitionWASM } from 'pshenmic-dpp';
+import { LATEST_PLATFORM_VERSION } from '../constants.js';
+const shieldedTransitionsMap = {
+    shield: {
+        method: ShieldedBuilderWASM.prototype.shield,
+        arguments: ['recipient', 'shieldAmount', 'inputs', 'privateKeys', 'feeStrategy', 'userFeeIncrease', 'memo'],
+        optionalArguments: ['senderOvk']
+    },
+    shieldFromAssetLock: {
+        method: ShieldedBuilderWASM.prototype.shieldFromAssetLock,
+        arguments: ['recipient', 'shieldAmount', 'assetLockProof', 'privateKey', 'memo', 'dummyOutputs'],
+        optionalArguments: ['senderOvk', 'surplusOutput']
+    },
+    shieldedWithdrawal: {
+        method: ShieldedBuilderWASM.prototype.shieldedWithdrawal,
+        arguments: ['spends', 'withdrawalAmount', 'outputScript', 'coreFeePerByte', 'pooling', 'changeAddress', 'seed', 'coinType', 'account', 'anchor', 'memo'],
+        optionalArguments: []
+    },
+    unshield: {
+        method: ShieldedBuilderWASM.prototype.unshield,
+        arguments: ['spends', 'outputAddress', 'unshieldAmount', 'changeAddress', 'seed', 'coinType', 'account', 'anchor', 'memo'],
+        optionalArguments: []
+    },
+    shieldedTransfer: {
+        method: ShieldedBuilderWASM.prototype.shieldedTransfer,
+        arguments: ['spends', 'recipient', 'transferAmount', 'changeAddress', 'seed', 'coinType', 'account', 'anchor', 'memo'],
+        optionalArguments: []
+    },
+    identityCreateFromShieldedPool: {
+        method: ShieldedBuilderWASM.prototype.identityCreateFromShieldedPool,
+        arguments: ['publicKeys', 'privateKeys', 'denomination', 'sendToAddressOnCreationFailure', 'spends', 'changeAddress', 'seed', 'coinType', 'account', 'anchor', 'memo'],
+        optionalArguments: []
+    }
+};
+export default function createStateTransition(builder, type, params) {
+    const { method: builderMethod, arguments: classArguments, optionalArguments } = shieldedTransitionsMap[type];
+    if (builderMethod == null) {
+        throw new Error(`Unimplemented shielded transition type: ${type}`);
+    }
+    const [missingArgument] = classArguments
+        .filter((classArgument) => params[classArgument] == null);
+    if (missingArgument != null) {
+        throw new Error(`Shielded transition param "${missingArgument}" is missing`);
+    }
+    const transitionParams = classArguments.concat(optionalArguments).map((classArgument) => params[classArgument]);
+    const result = builderMethod.apply(builder, [...transitionParams, params.platformVersion ?? LATEST_PLATFORM_VERSION]);
+    if (result instanceof StateTransitionWASM) {
+        return result;
+    }
+    if (result instanceof ShieldedWithdrawalResultWASM) {
+        return result.stateTransition;
+    }
+    const { denomination, sendToAddressOnCreationFailure } = params;
+    return new IdentityCreateFromShieldedPoolTransitionWASM(result.publicKeys, denomination, result.actions, result.anchor, result.proof, result.bindingsSignature, sendToAddressOnCreationFailure, result.identityId).toStateTransition();
+}

package/src/shielded/getMostRecentShieldedAnchor.d.ts

@@ -0,0 +1,2 @@
+import GRPCConnectionPool from '../grpcConnectionPool.js';
+export default function getMostRecentShieldedAnchor(grpcPool: GRPCConnectionPool): Promise<Uint8Array | undefined>;

package/src/shielded/getMostRecentShieldedAnchor.js

@@ -0,0 +1,36 @@
+import { GetMostRecentShieldedAnchorRequest } from '../../proto/generated/platform.js';
+import { verifyMostRecentShieldedAnchorProof } from "pshenmic-dpp";
+import { LATEST_PLATFORM_VERSION } from "../constants.js";
+import { getQuorumPublicKey } from "../utils/getQuorumPublicKey.js";
+import bytesToHex from "../utils/bytesToHex.js";
+import verifyTenderdashProof from "../utils/verifyTenderdashProof.js";
+export default async function getMostRecentShieldedAnchor(grpcPool) {
+    const getMostRecentShieldedAnchorRequest = GetMostRecentShieldedAnchorRequest.create({
+        version: {
+            oneofKind: 'v0',
+            v0: {
+                prove: true
+            }
+        }
+    });
+    const { response } = await grpcPool.getClient().getMostRecentShieldedAnchor(getMostRecentShieldedAnchorRequest);
+    const { version } = response;
+    if (version.oneofKind !== 'v0') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be v0)');
+    }
+    const { v0 } = version;
+    if (v0.result.oneofKind !== 'proof') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be proof)');
+    }
+    const { result: { proof }, metadata } = v0;
+    if (metadata == null) {
+        throw new Error('Metadata not found');
+    }
+    const { rootHash, anchor } = verifyMostRecentShieldedAnchorProof(proof.grovedbProof, true, LATEST_PLATFORM_VERSION);
+    const quorumPublicKey = await getQuorumPublicKey(grpcPool.network, proof.quorumType, bytesToHex(proof.quorumHash));
+    const verify = await verifyTenderdashProof(proof, metadata, rootHash, quorumPublicKey);
+    if (!verify) {
+        throw new Error('Failed to verify query');
+    }
+    return anchor;
+}

package/src/shielded/getShieldedAnchors.d.ts

@@ -0,0 +1,2 @@
+import GRPCConnectionPool from '../grpcConnectionPool.js';
+export default function getShieldedAnchors(grpcPool: GRPCConnectionPool): Promise<Uint8Array[]>;

package/src/shielded/getShieldedAnchors.js

@@ -0,0 +1,36 @@
+import { GetShieldedAnchorsRequest } from '../../proto/generated/platform.js';
+import { verifyShieldedAnchorsProof } from "pshenmic-dpp";
+import { LATEST_PLATFORM_VERSION } from "../constants.js";
+import { getQuorumPublicKey } from "../utils/getQuorumPublicKey.js";
+import bytesToHex from "../utils/bytesToHex.js";
+import verifyTenderdashProof from "../utils/verifyTenderdashProof.js";
+export default async function getShieldedAnchors(grpcPool) {
+    const getShieldedAnchorsRequest = GetShieldedAnchorsRequest.create({
+        version: {
+            oneofKind: 'v0',
+            v0: {
+                prove: true
+            }
+        }
+    });
+    const { response } = await grpcPool.getClient().getShieldedAnchors(getShieldedAnchorsRequest);
+    const { version } = response;
+    if (version.oneofKind !== 'v0') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be v0)');
+    }
+    const { v0 } = version;
+    if (v0.result.oneofKind !== 'proof') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be proof)');
+    }
+    const { result: { proof }, metadata } = v0;
+    if (metadata == null) {
+        throw new Error('Metadata not found');
+    }
+    const { rootHash, anchors } = verifyShieldedAnchorsProof(proof.grovedbProof, true, LATEST_PLATFORM_VERSION);
+    const quorumPublicKey = await getQuorumPublicKey(grpcPool.network, proof.quorumType, bytesToHex(proof.quorumHash));
+    const verify = await verifyTenderdashProof(proof, metadata, rootHash, quorumPublicKey);
+    if (!verify) {
+        throw new Error('Failed to verify query');
+    }
+    return anchors;
+}

package/src/shielded/getShieldedEncryptedNotes.d.ts

@@ -0,0 +1,3 @@
+import GRPCConnectionPool from '../grpcConnectionPool.js';
+import { ShieldedEncryptedNote } from '../../types.js';
+export default function getShieldedEncryptedNotes(grpcPool: GRPCConnectionPool, startIndex: bigint, count: number): Promise<ShieldedEncryptedNote[]>;

package/src/shielded/getShieldedEncryptedNotes.js

@@ -0,0 +1,43 @@
+import { GetShieldedEncryptedNotesRequest } from '../../proto/generated/platform.js';
+import { verifyShieldedEncryptedNotesProof } from "pshenmic-dpp";
+import { LATEST_PLATFORM_VERSION, SHIELDED_MAX_NOTES_PER_QUERY } from "../constants.js";
+import { getQuorumPublicKey } from "../utils/getQuorumPublicKey.js";
+import bytesToHex from "../utils/bytesToHex.js";
+import verifyTenderdashProof from "../utils/verifyTenderdashProof.js";
+export default async function getShieldedEncryptedNotes(grpcPool, startIndex, count) {
+    const getShieldedEncryptedNotesRequest = GetShieldedEncryptedNotesRequest.create({
+        version: {
+            oneofKind: 'v0',
+            v0: {
+                startIndex: startIndex.toString(),
+                count,
+                prove: true
+            }
+        }
+    });
+    const { response } = await grpcPool.getClient().getShieldedEncryptedNotes(getShieldedEncryptedNotesRequest);
+    const { version } = response;
+    if (version.oneofKind !== 'v0') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be v0)');
+    }
+    const { v0 } = version;
+    if (v0.result.oneofKind !== 'proof') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be proof)');
+    }
+    const { result: { proof }, metadata } = v0;
+    if (metadata == null) {
+        throw new Error('Metadata not found');
+    }
+    const { rootHash, notes } = verifyShieldedEncryptedNotesProof(proof.grovedbProof, startIndex, count, SHIELDED_MAX_NOTES_PER_QUERY, true, LATEST_PLATFORM_VERSION);
+    const quorumPublicKey = await getQuorumPublicKey(grpcPool.network, proof.quorumType, bytesToHex(proof.quorumHash));
+    const verify = await verifyTenderdashProof(proof, metadata, rootHash, quorumPublicKey);
+    if (!verify) {
+        throw new Error('Failed to verify query');
+    }
+    return notes.map(note => ({
+        nullifier: note.nullifier,
+        cmx: note.cmx,
+        encryptedNote: note.encryptedNote,
+        cvNet: note.cvNet
+    }));
+}

package/src/shielded/getShieldedNotesCount.d.ts

@@ -0,0 +1,2 @@
+import GRPCConnectionPool from '../grpcConnectionPool.js';
+export default function getShieldedNotesCount(grpcPool: GRPCConnectionPool): Promise<bigint | undefined>;

package/src/shielded/getShieldedNotesCount.js

@@ -0,0 +1,36 @@
+import { GetShieldedNotesCountRequest } from '../../proto/generated/platform.js';
+import { verifyShieldedNotesCountProof } from "pshenmic-dpp";
+import { LATEST_PLATFORM_VERSION } from "../constants.js";
+import { getQuorumPublicKey } from "../utils/getQuorumPublicKey.js";
+import bytesToHex from "../utils/bytesToHex.js";
+import verifyTenderdashProof from "../utils/verifyTenderdashProof.js";
+export default async function getShieldedNotesCount(grpcPool) {
+    const getShieldedNotesCountRequest = GetShieldedNotesCountRequest.create({
+        version: {
+            oneofKind: 'v0',
+            v0: {
+                prove: true
+            }
+        }
+    });
+    const { response } = await grpcPool.getClient().getShieldedNotesCount(getShieldedNotesCountRequest);
+    const { version } = response;
+    if (version.oneofKind !== 'v0') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be v0)');
+    }
+    const { v0 } = version;
+    if (v0.result.oneofKind !== 'proof') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be proof)');
+    }
+    const { result: { proof }, metadata } = v0;
+    if (metadata == null) {
+        throw new Error('Metadata not found');
+    }
+    const { rootHash, count } = verifyShieldedNotesCountProof(proof.grovedbProof, true, LATEST_PLATFORM_VERSION);
+    const quorumPublicKey = await getQuorumPublicKey(grpcPool.network, proof.quorumType, bytesToHex(proof.quorumHash));
+    const verify = await verifyTenderdashProof(proof, metadata, rootHash, quorumPublicKey);
+    if (!verify) {
+        throw new Error('Failed to verify query');
+    }
+    return count;
+}

package/src/shielded/getShieldedNullifiers.d.ts

@@ -0,0 +1,3 @@
+import GRPCConnectionPool from '../grpcConnectionPool.js';
+import { ShieldedNullifierStatus } from '../../types.js';
+export default function getShieldedNullifiers(grpcPool: GRPCConnectionPool, nullifiers: Uint8Array[]): Promise<ShieldedNullifierStatus[]>;

package/src/shielded/getShieldedNullifiers.js

@@ -0,0 +1,40 @@
+import { GetShieldedNullifiersRequest } from '../../proto/generated/platform.js';
+import { verifyShieldedNullifiersProof } from "pshenmic-dpp";
+import { LATEST_PLATFORM_VERSION } from "../constants.js";
+import { getQuorumPublicKey } from "../utils/getQuorumPublicKey.js";
+import bytesToHex from "../utils/bytesToHex.js";
+import verifyTenderdashProof from "../utils/verifyTenderdashProof.js";
+export default async function getShieldedNullifiers(grpcPool, nullifiers) {
+    const getShieldedNullifiersRequest = GetShieldedNullifiersRequest.create({
+        version: {
+            oneofKind: 'v0',
+            v0: {
+                nullifiers,
+                prove: true
+            }
+        }
+    });
+    const { response } = await grpcPool.getClient().getShieldedNullifiers(getShieldedNullifiersRequest);
+    const { version } = response;
+    if (version.oneofKind !== 'v0') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be v0)');
+    }
+    const { v0 } = version;
+    if (v0.result.oneofKind !== 'proof') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be proof)');
+    }
+    const { result: { proof }, metadata } = v0;
+    if (metadata == null) {
+        throw new Error('Metadata not found');
+    }
+    const { rootHash, nullifiers: nullifiersStatuses } = verifyShieldedNullifiersProof(proof.grovedbProof, nullifiers, true, LATEST_PLATFORM_VERSION);
+    const quorumPublicKey = await getQuorumPublicKey(grpcPool.network, proof.quorumType, bytesToHex(proof.quorumHash));
+    const verify = await verifyTenderdashProof(proof, metadata, rootHash, quorumPublicKey);
+    if (!verify) {
+        throw new Error('Failed to verify query');
+    }
+    return nullifiersStatuses.map(entry => ({
+        nullifier: entry.nullifier,
+        isSpent: entry.isSpent
+    }));
+}

package/src/shielded/getShieldedPoolState.d.ts

@@ -0,0 +1,2 @@
+import GRPCConnectionPool from '../grpcConnectionPool.js';
+export default function getShieldedPoolState(grpcPool: GRPCConnectionPool): Promise<bigint | undefined>;

package/src/shielded/getShieldedPoolState.js

@@ -0,0 +1,36 @@
+import { GetShieldedPoolStateRequest } from '../../proto/generated/platform.js';
+import { getQuorumPublicKey } from "../utils/getQuorumPublicKey.js";
+import bytesToHex from "../utils/bytesToHex.js";
+import verifyTenderdashProof from "../utils/verifyTenderdashProof.js";
+import { verifyShieldedPoolStateProof } from "pshenmic-dpp";
+import { LATEST_PLATFORM_VERSION } from "../constants.js";
+export default async function getShieldedPoolState(grpcPool) {
+    const getShieldedPoolStateRequest = GetShieldedPoolStateRequest.create({
+        version: {
+            oneofKind: 'v0',
+            v0: {
+                prove: true
+            }
+        }
+    });
+    const { response } = await grpcPool.getClient().getShieldedPoolState(getShieldedPoolStateRequest);
+    const { version } = response;
+    if (version.oneofKind !== 'v0') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be v0)');
+    }
+    const { v0 } = version;
+    if (v0.result.oneofKind !== 'proof') {
+        throw new Error('Unexpected oneOf type returned from DAPI (must be proof)');
+    }
+    const { result: { proof }, metadata } = v0;
+    if (metadata == null) {
+        throw new Error('Metadata not found');
+    }
+    const { rootHash, totalBalance } = verifyShieldedPoolStateProof(proof.grovedbProof, true, LATEST_PLATFORM_VERSION);
+    const quorumPublicKey = await getQuorumPublicKey(grpcPool.network, proof.quorumType, bytesToHex(proof.quorumHash));
+    const verify = await verifyTenderdashProof(proof, metadata, rootHash, quorumPublicKey);
+    if (!verify) {
+        throw new Error('Failed to verify query');
+    }
+    return totalBalance;
+}

package/src/shielded/index.d.ts

@@ -0,0 +1,130 @@
+import GRPCConnectionPool from '../grpcConnectionPool.js';
+import { ShieldedEncryptedNote, ShieldedNullifierStatus, ShieldedTransitionParamsMap, ShieldedTransitionType } from '../../types.js';
+import { RecoveredNoteWASM, ShieldedBuilderWASM, SpendableNoteWASM, StateTransitionWASM } from 'pshenmic-dpp';
+/**
+ * Shielded controller for requesting information about shielded pool
+ *
+ * @hideconstructor
+ */
+export declare class ShieldedController {
+    /** @ignore **/
+    grpcPool: GRPCConnectionPool;
+    /** @ignore **/
+    shieldedBuilder?: ShieldedBuilderWASM;
+    constructor(grpcPool: GRPCConnectionPool);
+    /**
+     * Set bindings instance of builder
+     * Needed for custom builder load, because ShieldedBuilderWASM inits very slow on old hardware
+     */
+    init(builder?: ShieldedBuilderWASM): ShieldedBuilderWASM;
+    /**
+     * Lazily constructs and caches a {ShieldedBuilderWASM}. Construction builds
+     * the Halo 2 proving key (~seconds), so the instance is created once and reused.
+     *
+     * @ignore
+     */
+    getShieldedBuilder(): ShieldedBuilderWASM;
+    /**
+     * Retrieves a batch of shielded encrypted notes from the shielded pool,
+     * starting from the given note index.
+     *
+     * Returns an array of encrypted notes, each containing the nullifier,
+     * note commitment (cmx), encrypted note payload and value commitment (cvNet).
+     *
+     * @param startIndex {bigint} - index of the first note to fetch
+     * @param count {number} - amount of notes to fetch
+     *
+     * @return {Promise<ShieldedEncryptedNote[]>}
+     */
+    getShieldedEncryptedNotes(startIndex: bigint, count: number): Promise<ShieldedEncryptedNote[]>;
+    /**
+     * Retrieves the set of valid anchors (note commitment tree roots) currently
+     * accepted by the shielded pool.
+     *
+     * @return {Promise<Uint8Array[]>}
+     */
+    getShieldedAnchors(): Promise<Uint8Array[]>;
+    /**
+     * Retrieves the most recent anchor (note commitment tree root) of the shielded pool.
+     *
+     * @return {Promise<Uint8Array>}
+     */
+    getMostRecentShieldedAnchor(): Promise<Uint8Array | undefined>;
+    /**
+     * Retrieves the total balance currently held in the shielded pool.
+     *
+     * @return {Promise<bigint>}
+     */
+    getShieldedPoolState(): Promise<bigint | undefined>;
+    /**
+     * Retrieves the total count of notes (leaves) in the shielded notes
+     * commitment tree. Useful as a denominator for shielded sync progress.
+     *
+     * @return {Promise<bigint>}
+     */
+    getShieldedNotesCount(): Promise<bigint | undefined>;
+    /**
+     * Checks the spent status of the given nullifiers in the shielded pool.
+     *
+     * Returns an array of statuses, each containing the nullifier and whether
+     * it has already been spent.
+     *
+     * @param nullifiers {Uint8Array[]} - nullifiers to check
+     *
+     * @return {Promise<ShieldedNullifierStatus[]>}
+     */
+    getShieldedNullifiers(nullifiers: Uint8Array[]): Promise<ShieldedNullifierStatus[]>;
+    /**
+     * Recovers the notes owned by a wallet from a set of shielded encrypted notes
+     * (as returned by {@link getShieldedEncryptedNotes}) by trial-decrypting each
+     * with the viewing key derived from the seed (ZIP-32 m/32'/coinType'/account').
+     * Only notes addressed to the wallet are returned, each with its global leaf
+     * position (`index`) in the commitment tree.
+     *
+     * @param notes {ShieldedEncryptedNote[]} - shielded encrypted notes to scan
+     * @param seed {Uint8Array} - BIP-39 seed bytes
+     * @param account {number} - ZIP-32 account index
+     *
+     * @return {RecoveredNoteWASM[]}
+     */
+    recoverNotes(notes: ShieldedEncryptedNote[], seed: Uint8Array, account: number): RecoveredNoteWASM[];
+    /**
+     * Rebuilds the note commitment tree from the full on-chain note set and
+     * witnesses the given recovered notes against it, producing the spendable
+     * notes and the shared anchor required by spend transitions (`shieldedTransfer`,
+     * `unshield`, `shieldedWithdrawal`, `identityCreateFromShieldedPool`).
+     *
+     * Pass the complete note set from {@link getShieldedEncryptedNotes} as `notes`
+     * (the commitment tree leaves) and the notes you want to spend from
+     * {@link recoverNotes} as `recovered`. This keeps the whole spend flow inside
+     * the SDK — no need to construct a commitment tree yourself.
+     *
+     * @param notes {ShieldedEncryptedNote[]} - full on-chain note set (the tree leaves)
+     * @param recovered {RecoveredNoteWASM[]} - the recovered notes to spend
+     *
+     * @return {{ spends: SpendableNoteWASM[], anchor: Uint8Array }}
+     */
+    buildSpendableNotes(notes: ShieldedEncryptedNote[], recovered: RecoveredNoteWASM[]): {
+        spends: SpendableNoteWASM[];
+        anchor: Uint8Array;
+    };
+    /**
+     * Helper function for building and proving shielded (Orchard) transitions.
+     * It may be used to create any of 6 shielded transition actions:
+     *
+     * 1) shield - transparent platform addresses -> pool (deposit)
+     * 2) shieldFromAssetLock - asset lock -> pool (deposit)
+     * 3) shieldedWithdrawal - pool -> core L1 (spend)
+     * 4) unshield - pool -> platform identity balance (spend)
+     * 5) shieldedTransfer - pool -> pool (spend)
+     * 6) identityCreateFromShieldedPool - pool -> new identity (spend)
+     *
+     * Spends require a {SpendableNoteWASM} witnessed against an on-chain anchor.
+     *
+     * @param type {string} Type of the shielded transition, must be one of ('shield' | 'shieldFromAssetLock' | 'shieldedWithdrawal' | 'unshield' | 'shieldedTransfer' | 'identityCreateFromShieldedPool')
+     * @param params {ShieldedTransitionParams} params
+     *
+     * @return {StateTransitionWASM}
+     */
+    createStateTransition<K extends ShieldedTransitionType>(type: K, params: ShieldedTransitionParamsMap[K]): StateTransitionWASM;
+}