pshenmic-dpp 2.0.0-dev.27 → 2.0.0-dev.29

package/dist/src/dpp/verify/AddressFunds/utils.js

@@ -0,0 +1,28 @@
+export function mapGroveElementEntry(entry) {
+    const { element } = entry;
+    return {
+        key: entry.key,
+        element: {
+            type: element.type,
+            wrapper: element.wrapper != null ? element.wrapper : undefined,
+            value: element.value ?? undefined,
+            sum: element.sum != null ? BigInt(element.sum) : undefined,
+            count: element.count != null ? BigInt(element.count) : undefined
+        }
+    };
+}
+export function mapGroveLeafInfo(info) {
+    return {
+        key: info.key,
+        hash: info.hash,
+        count: info.count != null ? BigInt(info.count) : undefined
+    };
+}
+export function mapGroveAncestor(ancestor) {
+    return {
+        levelsUp: ancestor.levelsUp,
+        count: BigInt(ancestor.count),
+        key: ancestor.key,
+        hash: ancestor.hash
+    };
+}

package/dist/src/dpp/verify/AddressFunds/verifyAddressesBranchState.d.ts

@@ -0,0 +1,12 @@
+import { PlatformVersionLike, VerifiedAddressesBranchState } from '../../types.js';
+/**
+ * Verifies a branch chunk proof for the address funds tree.
+ *
+ * `expectedRootHash` must be the `hash` the parent trunk or branch reported for
+ * `key`; it is what anchors this subtree to the proven root, so the result
+ * carries no root hash of its own.
+ *
+ * `depth` is validated against an allowed range, so take it from the parent
+ * trunk's `chunkDepths` rather than picking a value.
+ */
+export declare function verifyAddressesBranchState(proof: Uint8Array, key: Uint8Array, depth: number, expectedRootHash: Uint8Array, platformVersion: PlatformVersionLike): VerifiedAddressesBranchState;

package/dist/src/dpp/verify/AddressFunds/verifyAddressesBranchState.js

@@ -0,0 +1,29 @@
+import { dppProvider } from '../../provider.js';
+import { valueToDynamicValue } from '../../utils.js';
+import { mapGroveAncestor, mapGroveElementEntry, mapGroveLeafInfo } from './utils.js';
+/**
+ * Verifies a branch chunk proof for the address funds tree.
+ *
+ * `expectedRootHash` must be the `hash` the parent trunk or branch reported for
+ * `key`; it is what anchors this subtree to the proven root, so the result
+ * carries no root hash of its own.
+ *
+ * `depth` is validated against an allowed range, so take it from the parent
+ * trunk's `chunkDepths` rather than picking a value.
+ */
+export function verifyAddressesBranchState(proof, key, depth, expectedRootHash, platformVersion) {
+    const result = dppProvider.dpp.verifyAddressesBranchState(proof, key, depth, expectedRootHash, valueToDynamicValue(platformVersion));
+    return {
+        elements: result.elements.map(mapGroveElementEntry),
+        leafKeys: result.leafKeys.map(mapGroveLeafInfo),
+        branchRootHash: result.branchRootHash,
+        traceKeyToLeaf: (traced) => {
+            const leaf = result.traceKeyToLeaf(traced);
+            return leaf != null ? mapGroveLeafInfo(leaf) : undefined;
+        },
+        getAncestor: (leafKey, minPrivacyTreeCount) => {
+            const ancestor = result.getAncestor(leafKey, minPrivacyTreeCount.toString());
+            return ancestor != null ? mapGroveAncestor(ancestor) : undefined;
+        }
+    };
+}

package/dist/src/dpp/verify/AddressFunds/verifyAddressesTrunkState.d.ts

@@ -0,0 +1,9 @@
+import { PlatformVersionLike, VerifiedAddressesTrunkState } from '../../types.js';
+/**
+ * Verifies a trunk chunk proof for the address funds tree.
+ *
+ * The trunk covers the top of the tree only. Subtrees below it are truncated
+ * and listed in `leafKeys`; use `traceKeyToLeaf` to find which one holds an
+ * address, then fetch it with `verifyAddressesBranchState`.
+ */
+export declare function verifyAddressesTrunkState(proof: Uint8Array, platformVersion: PlatformVersionLike): VerifiedAddressesTrunkState;

package/dist/src/dpp/verify/AddressFunds/verifyAddressesTrunkState.js

@@ -0,0 +1,30 @@
+import { dppProvider } from '../../provider.js';
+import { valueToDynamicValue } from '../../utils.js';
+import { mapGroveAncestor, mapGroveElementEntry, mapGroveLeafInfo } from './utils.js';
+/**
+ * Verifies a trunk chunk proof for the address funds tree.
+ *
+ * The trunk covers the top of the tree only. Subtrees below it are truncated
+ * and listed in `leafKeys`; use `traceKeyToLeaf` to find which one holds an
+ * address, then fetch it with `verifyAddressesBranchState`.
+ */
+export function verifyAddressesTrunkState(proof, platformVersion) {
+    const result = dppProvider.dpp.verifyAddressesTrunkState(proof, valueToDynamicValue(platformVersion));
+    return {
+        rootHash: result.rootHash,
+        elements: result.elements.map(mapGroveElementEntry),
+        leafKeys: result.leafKeys.map(mapGroveLeafInfo),
+        chunkDepths: result.chunkDepths,
+        maxTreeDepth: result.maxTreeDepth,
+        // These close over the verified result because tracing walks the proof's
+        // reconstructed tree, which is not projected into plain data.
+        traceKeyToLeaf: (key) => {
+            const leaf = result.traceKeyToLeaf(key);
+            return leaf != null ? mapGroveLeafInfo(leaf) : undefined;
+        },
+        getAncestor: (leafKey, minPrivacyTreeCount) => {
+            const ancestor = result.getAncestor(leafKey, minPrivacyTreeCount.toString());
+            return ancestor != null ? mapGroveAncestor(ancestor) : undefined;
+        }
+    };
+}

package/dist/src/dpp/verify/AddressFunds/verifyRecentAddressBalanceChanges.d.ts

@@ -0,0 +1,9 @@
+import { PlatformVersionLike, VerifiedRecentAddressBalanceChanges } from '../../types.js';
+/**
+ * Verifies a proof of the address balance changes from a block height onwards.
+ *
+ * `startHeightExclusive` must match the flag the proof was requested with: it
+ * selects a range starting just past `startBlockHeight` rather than at it, and
+ * the two produce different queries, so a mismatch fails verification.
+ */
+export declare function verifyRecentAddressBalanceChanges(proof: Uint8Array, startBlockHeight: bigint, startHeightExclusive: boolean, limit: number | undefined, verifySubsetOfProof: boolean, platformVersion: PlatformVersionLike): VerifiedRecentAddressBalanceChanges;

package/dist/src/dpp/verify/AddressFunds/verifyRecentAddressBalanceChanges.js

@@ -0,0 +1,24 @@
+import { dppProvider } from '../../provider.js';
+import { valueToDynamicValue } from '../../utils.js';
+import { PlatformAddressWASM } from '../../structs/PlatformAddress/PlatformAddress.js';
+/**
+ * Verifies a proof of the address balance changes from a block height onwards.
+ *
+ * `startHeightExclusive` must match the flag the proof was requested with: it
+ * selects a range starting just past `startBlockHeight` rather than at it, and
+ * the two produce different queries, so a mismatch fails verification.
+ */
+export function verifyRecentAddressBalanceChanges(proof, startBlockHeight, startHeightExclusive, limit, verifySubsetOfProof, platformVersion) {
+    const result = dppProvider.dpp.verifyRecentAddressBalanceChanges(proof, startBlockHeight.toString(), startHeightExclusive, limit, verifySubsetOfProof, valueToDynamicValue(platformVersion));
+    return {
+        rootHash: result.rootHash,
+        blocks: result.blocks.map((block) => ({
+            blockHeight: BigInt(block.blockHeight),
+            changes: block.changes.map((change) => ({
+                address: PlatformAddressWASM.createFromRawInstance(change.address),
+                operation: change.operation,
+                credits: BigInt(change.credits)
+            }))
+        }))
+    };
+}

package/dist/src/dpp/verify/AddressFunds/verifyRecentCompactedAddressBalanceChanges.d.ts

@@ -0,0 +1,10 @@
+import { PlatformVersionLike, VerifiedRecentCompactedAddressBalanceChanges } from '../../types.js';
+/**
+ * Verifies a proof of the compacted address balance changes from a block height
+ * onwards, where each entry merges a range of blocks.
+ *
+ * There is no subset flag here: the proof is a self-contained envelope whose
+ * predecessor half authenticates which range covers the requested height, so
+ * the forward half has nothing to be a subset of.
+ */
+export declare function verifyRecentCompactedAddressBalanceChanges(proof: Uint8Array, startBlockHeight: bigint, limit: number | undefined, platformVersion: PlatformVersionLike): VerifiedRecentCompactedAddressBalanceChanges;

package/dist/src/dpp/verify/AddressFunds/verifyRecentCompactedAddressBalanceChanges.js

@@ -0,0 +1,30 @@
+import { dppProvider } from '../../provider.js';
+import { valueToDynamicValue } from '../../utils.js';
+import { PlatformAddressWASM } from '../../structs/PlatformAddress/PlatformAddress.js';
+/**
+ * Verifies a proof of the compacted address balance changes from a block height
+ * onwards, where each entry merges a range of blocks.
+ *
+ * There is no subset flag here: the proof is a self-contained envelope whose
+ * predecessor half authenticates which range covers the requested height, so
+ * the forward half has nothing to be a subset of.
+ */
+export function verifyRecentCompactedAddressBalanceChanges(proof, startBlockHeight, limit, platformVersion) {
+    const result = dppProvider.dpp.verifyRecentCompactedAddressBalanceChanges(proof, startBlockHeight.toString(), limit, valueToDynamicValue(platformVersion));
+    return {
+        rootHash: result.rootHash,
+        ranges: result.ranges.map((range) => ({
+            startBlockHeight: BigInt(range.startBlockHeight),
+            endBlockHeight: BigInt(range.endBlockHeight),
+            changes: range.changes.map((change) => ({
+                address: PlatformAddressWASM.createFromRawInstance(change.address),
+                operation: change.operation,
+                setCredits: change.setCredits != null ? BigInt(change.setCredits) : undefined,
+                addToCreditsOperations: change.addToCreditsOperations.map((operation) => ({
+                    blockHeight: BigInt(operation.blockHeight),
+                    credits: BigInt(operation.credits)
+                }))
+            }))
+        }))
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pshenmic-dpp",
-  "version": "2.0.0-dev.27",
+  "version": "2.0.0-dev.29",
   "main": "dist/src/wasm.js",
   "types": "dist/src/wasm.d.ts",
   "react-native": "./dist/src/react-native.js",

package/tests/unit/Shielded.spec.ts

@@ -1,6 +1,8 @@
 import {
   ShieldedMemoWASM,
   OrchardAddressWASM,
+  FullViewingKeyWASM,
+  IncomingViewingKeyWASM,
   orchardOvkFromSeed,
   NoteWASM,
   MerklePathWASM,
@@ -169,6 +171,180 @@ describe('OrchardAddress', function () {
       expect(ovk.length).toEqual(32)
     })
   })
+
+  describe('fromFullViewingKey', function () {
+    test('should match the address derived from the same seed', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(OrchardAddressWASM.fromFullViewingKey(fvk).bytes())
+        .toEqual(OrchardAddressWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT).bytes())
+    })
+
+    test('should derive a different address per diversifier index', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(OrchardAddressWASM.fromFullViewingKey(fvk, 1).bytes())
+        .not.toEqual(OrchardAddressWASM.fromFullViewingKey(fvk, 0).bytes())
+    })
+
+    test('should derive a different address per scope', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(OrchardAddressWASM.fromFullViewingKey(fvk, 0, 'internal').bytes())
+        .not.toEqual(OrchardAddressWASM.fromFullViewingKey(fvk, 0, 'external').bytes())
+    })
+
+    test('should reject an unknown scope', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(() => OrchardAddressWASM.fromFullViewingKey(fvk, 0, 'nope' as any)).toThrow()
+    })
+  })
+
+  describe('fromIncomingViewingKey', function () {
+    test('should match the address derived from the same seed', function () {
+      const ivk = IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(OrchardAddressWASM.fromIncomingViewingKey(ivk).bytes())
+        .toEqual(OrchardAddressWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT).bytes())
+    })
+
+    test('should derive a different address per diversifier index', function () {
+      const ivk = IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(OrchardAddressWASM.fromIncomingViewingKey(ivk, 7).bytes())
+        .not.toEqual(OrchardAddressWASM.fromIncomingViewingKey(ivk, 0).bytes())
+    })
+  })
+
+  describe('fromSeed scope', function () {
+    test('should derive the internal-scope address', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(OrchardAddressWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT, 0, 'internal').bytes())
+        .toEqual(OrchardAddressWASM.fromFullViewingKey(fvk, 0, 'internal').bytes())
+    })
+  })
+})
+
+describe('FullViewingKey', function () {
+  describe('fromSeed', function () {
+    test('should derive a 96-byte key deterministically', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(fvk).toBeInstanceOf(FullViewingKeyWASM)
+      expect(fvk.bytes().length).toEqual(96)
+      expect(fvk.bytes()).toEqual(FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT).bytes())
+    })
+
+    test('should differ per account', function () {
+      expect(FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, 1).bytes())
+        .not.toEqual(FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, 0).bytes())
+    })
+
+    test('should reject a hardened account index', function () {
+      expect(() => FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, 0x80000000)).toThrow()
+    })
+  })
+
+  describe('serialization', function () {
+    test('should roundtrip through bytes', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(FullViewingKeyWASM.fromBytes(fvk.bytes()).bytes()).toEqual(fvk.bytes())
+    })
+
+    test('should reject bytes of the wrong length', function () {
+      expect(() => FullViewingKeyWASM.fromBytes(new Uint8Array(64))).toThrow()
+    })
+
+    test('should reject bytes that are not a valid key', function () {
+      expect(() => FullViewingKeyWASM.fromBytes(new Uint8Array(96).fill(0xff))).toThrow()
+    })
+  })
+
+  describe('toOvk', function () {
+    test('should match orchardOvkFromSeed for the external scope', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(fvk.toOvk()).toEqual(orchardOvkFromSeed(SEED, COIN_TYPE, ACCOUNT))
+      expect(fvk.toOvk('internal')).not.toEqual(fvk.toOvk('external'))
+    })
+  })
+
+  describe('toIvk', function () {
+    test('should derive the same key as IncomingViewingKey.fromSeed', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(fvk.toIvk().bytes())
+        .toEqual(IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT).bytes())
+      expect(fvk.toIvk('internal').bytes()).not.toEqual(fvk.toIvk('external').bytes())
+    })
+  })
+
+  describe('scopeForAddress', function () {
+    test('should report the scope of its own addresses', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(fvk.scopeForAddress(fvk.address(0, 'external'))).toEqual('External')
+      expect(fvk.scopeForAddress(fvk.address(0, 'internal'))).toEqual('Internal')
+    })
+
+    test('should return null for a foreign address', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+      const other = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, 1)
+
+      expect(fvk.scopeForAddress(other.address())).toBeNull()
+    })
+  })
+})
+
+describe('IncomingViewingKey', function () {
+  describe('fromSeed', function () {
+    test('should derive a 64-byte key deterministically', function () {
+      const ivk = IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(ivk).toBeInstanceOf(IncomingViewingKeyWASM)
+      expect(ivk.bytes().length).toEqual(64)
+      expect(ivk.bytes()).toEqual(IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT).bytes())
+    })
+  })
+
+  describe('fromFullViewingKey', function () {
+    test('should match the key derived from the same seed', function () {
+      const fvk = FullViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(IncomingViewingKeyWASM.fromFullViewingKey(fvk).bytes())
+        .toEqual(IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT).bytes())
+    })
+  })
+
+  describe('serialization', function () {
+    test('should roundtrip through bytes', function () {
+      const ivk = IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(IncomingViewingKeyWASM.fromBytes(ivk.bytes()).bytes()).toEqual(ivk.bytes())
+    })
+
+    test('should reject bytes of the wrong length', function () {
+      expect(() => IncomingViewingKeyWASM.fromBytes(new Uint8Array(96))).toThrow()
+    })
+  })
+
+  describe('diversifierIndex', function () {
+    test('should recover the index of its own address', function () {
+      const ivk = IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+
+      expect(ivk.diversifierIndex(ivk.address(5))).toEqual(5)
+    })
+
+    test('should return null for a foreign address', function () {
+      const ivk = IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, ACCOUNT)
+      const other = IncomingViewingKeyWASM.fromSeed(SEED, COIN_TYPE, 1)
+
+      expect(ivk.diversifierIndex(other.address())).toBeNull()
+    })
+  })
 })
 
 describe('Note', function () {