pshenmic-dpp 2.0.0-dev.26 → 2.0.0-dev.28

package/dist/src/dpp/types.d.ts

@@ -373,3 +373,85 @@ export interface VerifiedShieldedNullifiers {
     rootHash: Uint8Array;
     nullifiers: VerifiedShieldedNullifier[];
 }
+export type AddressBalanceOperation = 'setCredits' | 'addToCredits';
+export interface AddressBalanceChange {
+    address: PlatformAddressWASM;
+    /** `setCredits` means `credits` is the new balance, `addToCredits` means it is the delta. */
+    operation: AddressBalanceOperation;
+    credits: bigint;
+}
+export interface BlockAddressBalanceChanges {
+    blockHeight: bigint;
+    changes: AddressBalanceChange[];
+}
+export interface VerifiedRecentAddressBalanceChanges {
+    rootHash: Uint8Array;
+    blocks: BlockAddressBalanceChanges[];
+}
+export type CompactedAddressBalanceOperation = 'setCredits' | 'addToCreditsOperations';
+export interface BlockHeightCredit {
+    blockHeight: bigint;
+    credits: bigint;
+}
+export interface CompactedAddressBalanceChange {
+    address: PlatformAddressWASM;
+    operation: CompactedAddressBalanceOperation;
+    /** Populated when `operation` is `setCredits`. */
+    setCredits?: bigint;
+    /** Populated when `operation` is `addToCreditsOperations`, otherwise empty. */
+    addToCreditsOperations: BlockHeightCredit[];
+}
+export interface CompactedBlockAddressBalanceChanges {
+    startBlockHeight: bigint;
+    endBlockHeight: bigint;
+    changes: CompactedAddressBalanceChange[];
+}
+export interface VerifiedRecentCompactedAddressBalanceChanges {
+    rootHash: Uint8Array;
+    ranges: CompactedBlockAddressBalanceChanges[];
+}
+export type GroveElementType = 'Item' | 'ItemWithSumItem' | 'SumItem' | 'Reference' | 'ReferenceWithSumItem' | 'Tree' | 'SumTree' | 'BigSumTree' | 'ProvableSumTree' | 'CountTree' | 'ProvableCountTree' | 'CountSumTree' | 'ProvableCountSumTree' | 'ProvableCountProvableSumTree' | 'CommitmentTree' | 'MmrTree' | 'BulkAppendTree' | 'DenseAppendOnlyFixedSizeTree';
+export type GroveElementWrapper = 'NonCounted' | 'NotSummed' | 'NotCountedOrSummed';
+export interface GroveElement {
+    type: GroveElementType;
+    /** Set when the element opts out of its parent's aggregates; `type` still describes the wrapped element. */
+    wrapper?: GroveElementWrapper;
+    /** An item's payload, or a subtree's root key. Absent for empty subtrees. */
+    value?: Uint8Array;
+    sum?: bigint;
+    count?: bigint;
+}
+export interface GroveElementEntry {
+    key: Uint8Array;
+    element: GroveElement;
+}
+export interface GroveLeafInfo {
+    key: Uint8Array;
+    /** Pass as `expectedRootHash` when verifying this key's branch proof. */
+    hash: Uint8Array;
+    count?: bigint;
+}
+export interface GroveAncestor {
+    levelsUp: number;
+    count: bigint;
+    key: Uint8Array;
+    hash: Uint8Array;
+}
+export interface VerifiedAddressesTrunkState {
+    rootHash: Uint8Array;
+    elements: GroveElementEntry[];
+    /** Subtrees the trunk stops at. Empty when the whole tree fit in the trunk. */
+    leafKeys: GroveLeafInfo[];
+    chunkDepths: number[];
+    maxTreeDepth: number;
+    /** Which truncated subtree would hold `key`, or undefined if it is already in `elements`. */
+    traceKeyToLeaf: (key: Uint8Array) => GroveLeafInfo | undefined;
+    getAncestor: (leafKey: Uint8Array, minPrivacyTreeCount: bigint) => GroveAncestor | undefined;
+}
+export interface VerifiedAddressesBranchState {
+    elements: GroveElementEntry[];
+    leafKeys: GroveLeafInfo[];
+    branchRootHash: Uint8Array;
+    traceKeyToLeaf: (key: Uint8Array) => GroveLeafInfo | undefined;
+    getAncestor: (leafKey: Uint8Array, minPrivacyTreeCount: bigint) => GroveAncestor | undefined;
+}

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

@@ -0,0 +1,5 @@
+import type * as protocol from '../../../../binaries/bindingsTypes.js';
+import { GroveAncestor, GroveElementEntry, GroveLeafInfo } from '../../types.js';
+export declare function mapGroveElementEntry(entry: protocol.GroveElementEntryNAPI): GroveElementEntry;
+export declare function mapGroveLeafInfo(info: protocol.GroveLeafInfoNAPI): GroveLeafInfo;
+export declare function mapGroveAncestor(ancestor: protocol.GroveAncestorNAPI): GroveAncestor;

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.26",
+  "version": "2.0.0-dev.28",
   "main": "dist/src/wasm.js",
   "types": "dist/src/wasm.d.ts",
   "react-native": "./dist/src/react-native.js",

package/tests/unit/AddressTransitionsFees.spec.ts

@@ -0,0 +1,274 @@
+import {
+  AddressCreditWithdrawalTransitionWASM,
+  AddressFundingFromAssetLockTransitionWASM,
+  AddressFundsFeeStrategyStepWASM,
+  AddressFundsTransferTransitionWASM,
+  AddressWitnessWASM,
+  AssetLockProofWASM,
+  CoreScriptWASM,
+  IdentityCreateFromAddressesTransitionWASM,
+  IdentityCreditTransferToAddressesTransitionWASM,
+  IdentityPublicKeyInCreationWASM,
+  IdentityTopUpFromAddressesTransitionWASM,
+  InputAddressWASM,
+  KeyType,
+  OutPointWASM,
+  OutputAddressNullableCreditsWASM,
+  OutputAddressWASM,
+  PlatformAddressWASM,
+  PlatformVersionWASM,
+  Purpose,
+  SecurityLevel
+} from 'pshenmic-dpp'
+
+// Min fee components from the platform fee version (STATE_TRANSITION_MIN_FEES_VERSION1)
+// Storage charged by the node for one address balance entry that does not exist yet,
+// as pinned by platform's own fee regression suite.
+const NEW_ADDRESS_STORAGE_FEE = BigInt(6075000)
+const INPUT_COST = BigInt(500000)
+const OUTPUT_COST = BigInt(6000000)
+const ADDRESS_CREDIT_WITHDRAWAL_COST = BigInt(400000000)
+const IDENTITY_CREATE_BASE_COST = BigInt(2000000)
+const IDENTITY_KEY_IN_CREATION_COST = BigInt(6500000)
+const IDENTITY_TOPUP_BASE_COST = BigInt(500000)
+const CREDIT_TRANSFER_TO_ADDRESSES_COST = BigInt(500000)
+
+function randomBytes (length: number): Uint8Array {
+  const bytes = new Uint8Array(length)
+  for (let i = 0; i < length; i++) {
+    bytes[i] = Math.floor(Math.random() * 256)
+  }
+  return bytes
+}
+
+function createTestAddress (): PlatformAddressWASM {
+  const addressBytes = new Uint8Array(21)
+  addressBytes[0] = 0x00
+  addressBytes.set(randomBytes(20), 1)
+  return PlatformAddressWASM.fromBytes(addressBytes)
+}
+
+function createTestInputs (count: number): InputAddressWASM[] {
+  return Array.from(
+    { length: count },
+    () => new InputAddressWASM(createTestAddress(), 0, BigInt(500000000))
+  )
+}
+
+function createTestOutputs (count: number): OutputAddressWASM[] {
+  return Array.from(
+    { length: count },
+    () => new OutputAddressWASM(createTestAddress(), BigInt(100000))
+  )
+}
+
+function createTestWitnesses (count: number): AddressWitnessWASM[] {
+  return Array.from({ length: count }, () => AddressWitnessWASM.P2PKH(randomBytes(65)))
+}
+
+const feeStrategy = (): AddressFundsFeeStrategyStepWASM[] =>
+  [AddressFundsFeeStrategyStepWASM.DeductFromInput(0)]
+
+describe('AddressFundsTransferTransition fees', function () {
+  describe('estimateMinFee', function () {
+    test('should price inputs and outputs', function () {
+      expect(AddressFundsTransferTransitionWASM.estimateMinFee(1, 1))
+        .toEqual(INPUT_COST + OUTPUT_COST)
+
+      expect(AddressFundsTransferTransitionWASM.estimateMinFee(2, 3))
+        .toEqual(INPUT_COST * BigInt(2) + OUTPUT_COST * BigInt(3))
+    })
+
+    test('should charge at least one output', function () {
+      expect(AddressFundsTransferTransitionWASM.estimateMinFee(1, 0))
+        .toEqual(AddressFundsTransferTransitionWASM.estimateMinFee(1, 1))
+    })
+
+    test('should grow with the input and output counts', function () {
+      const one = AddressFundsTransferTransitionWASM.estimateMinFee(1, 1)
+      const two = AddressFundsTransferTransitionWASM.estimateMinFee(2, 2)
+
+      expect(two).toBeGreaterThan(one)
+    })
+
+    test('should default to the latest platform version', function () {
+      expect(AddressFundsTransferTransitionWASM.estimateMinFee(1, 1))
+        .toEqual(AddressFundsTransferTransitionWASM.estimateMinFee(1, 1, PlatformVersionWASM.PLATFORM_V13))
+    })
+  })
+
+  describe('calculateMinRequiredFee', function () {
+    test('should match the estimate for the transition inputs and outputs', function () {
+      const transition = new AddressFundsTransferTransitionWASM(
+        createTestInputs(2),
+        feeStrategy(),
+        0,
+        createTestWitnesses(2),
+        createTestOutputs(1)
+      )
+
+      expect(transition.calculateMinRequiredFee())
+        .toEqual(AddressFundsTransferTransitionWASM.estimateMinFee(2, 1))
+    })
+  })
+})
+
+describe('AddressCreditWithdrawalTransition fees', function () {
+  const outputScript = (): CoreScriptWASM => CoreScriptWASM.newP2PKH(randomBytes(20))
+
+  describe('estimateMinFee', function () {
+    test('should price the withdrawal, its inputs and its change output', function () {
+      expect(AddressCreditWithdrawalTransitionWASM.estimateMinFee(1, false))
+        .toEqual(ADDRESS_CREDIT_WITHDRAWAL_COST + INPUT_COST)
+
+      expect(AddressCreditWithdrawalTransitionWASM.estimateMinFee(1, true))
+        .toEqual(ADDRESS_CREDIT_WITHDRAWAL_COST + INPUT_COST + OUTPUT_COST)
+    })
+
+    test('should grow with the input count', function () {
+      expect(AddressCreditWithdrawalTransitionWASM.estimateMinFee(2, false))
+        .toBeGreaterThan(AddressCreditWithdrawalTransitionWASM.estimateMinFee(1, false))
+    })
+  })
+
+  describe('calculateMinRequiredFee', function () {
+    test('should match the estimate without a change output', function () {
+      const transition = new AddressCreditWithdrawalTransitionWASM(
+        createTestInputs(1),
+        feeStrategy(),
+        1,
+        'Standard',
+        outputScript(),
+        0,
+        createTestWitnesses(1)
+      )
+
+      expect(transition.calculateMinRequiredFee())
+        .toEqual(AddressCreditWithdrawalTransitionWASM.estimateMinFee(1, false))
+    })
+
+    test('should match the estimate with a change output', function () {
+      const transition = new AddressCreditWithdrawalTransitionWASM(
+        createTestInputs(1),
+        feeStrategy(),
+        1,
+        'Standard',
+        outputScript(),
+        0,
+        createTestWitnesses(1),
+        createTestOutputs(1)[0]
+      )
+
+      expect(transition.calculateMinRequiredFee())
+        .toEqual(AddressCreditWithdrawalTransitionWASM.estimateMinFee(1, true))
+    })
+  })
+})
+
+describe('IdentityCreateFromAddressesTransition fees', function () {
+  test('calculateMinRequiredFee should price the base cost, inputs, output and keys', function () {
+    const publicKeys = [
+      new IdentityPublicKeyInCreationWASM(
+        0,
+        Purpose.AUTHENTICATION,
+        SecurityLevel.MASTER,
+        KeyType.ECDSA_SECP256K1,
+        false,
+        randomBytes(33)
+      )
+    ]
+
+    const transition = new IdentityCreateFromAddressesTransitionWASM(
+      publicKeys,
+      createTestInputs(1),
+      feeStrategy(),
+      0,
+      createTestWitnesses(1),
+      createTestOutputs(1)[0]
+    )
+
+    expect(transition.calculateMinRequiredFee()).toEqual(
+      IDENTITY_CREATE_BASE_COST + INPUT_COST + OUTPUT_COST + IDENTITY_KEY_IN_CREATION_COST
+    )
+  })
+})
+
+describe('IdentityTopUpFromAddressesTransition fees', function () {
+  test('calculateMinRequiredFee should price the base cost, inputs and output', function () {
+    const transition = new IdentityTopUpFromAddressesTransitionWASM(
+      randomBytes(32),
+      createTestInputs(1),
+      feeStrategy(),
+      0,
+      createTestWitnesses(1),
+      createTestOutputs(1)[0]
+    )
+
+    expect(transition.calculateMinRequiredFee())
+      .toEqual(IDENTITY_TOPUP_BASE_COST + INPUT_COST + OUTPUT_COST)
+  })
+})
+
+describe('IdentityCreditTransferToAddressesTransition fees', function () {
+  test('calculateMinRequiredFee should price the base cost and each recipient', function () {
+    const transition = new IdentityCreditTransferToAddressesTransitionWASM(
+      randomBytes(32),
+      createTestOutputs(2),
+      BigInt(1),
+      0
+    )
+
+    expect(transition.calculateMinRequiredFee())
+      .toEqual(CREDIT_TRANSFER_TO_ADDRESSES_COST + OUTPUT_COST * BigInt(2))
+  })
+})
+
+describe('AddressFundingFromAssetLockTransition fees', function () {
+  test('calculateMinRequiredFee should include the asset lock base cost', function () {
+    const outPoint = new OutPointWASM('a'.repeat(64), 0)
+    const assetLockProof = AssetLockProofWASM.createChainAssetLockProof(100, outPoint)
+
+    const transition = new AddressFundingFromAssetLockTransitionWASM(
+      assetLockProof,
+      createTestInputs(1),
+      feeStrategy(),
+      0,
+      createTestWitnesses(1),
+      [new OutputAddressNullableCreditsWASM(createTestAddress(), BigInt(100000))]
+    )
+
+    const fee = transition.calculateMinRequiredFee()
+
+    expect(typeof fee).toEqual('bigint')
+    expect(fee).toBeGreaterThan(INPUT_COST + OUTPUT_COST)
+  })
+})
+
+describe('new address storage fee', function () {
+  test('should match the storage the node charges for one created address', function () {
+    expect(PlatformAddressWASM.estimateStorageFeeForNewAddresses(1))
+      .toEqual(NEW_ADDRESS_STORAGE_FEE)
+  })
+
+  test('should scale with the number of created addresses', function () {
+    expect(PlatformAddressWASM.estimateStorageFeeForNewAddresses(0)).toEqual(BigInt(0))
+    expect(PlatformAddressWASM.estimateStorageFeeForNewAddresses(3))
+      .toEqual(NEW_ADDRESS_STORAGE_FEE * BigInt(3))
+  })
+
+  test('should default to the latest platform version', function () {
+    expect(PlatformAddressWASM.estimateStorageFeeForNewAddresses(1))
+      .toEqual(PlatformAddressWASM.estimateStorageFeeForNewAddresses(1, PlatformVersionWASM.PLATFORM_V13))
+  })
+
+  test('should exceed the per output component of the min fee', function () {
+    const perOutput =
+      AddressFundsTransferTransitionWASM.estimateMinFee(1, 2) -
+      AddressFundsTransferTransitionWASM.estimateMinFee(1, 1)
+
+    // The min fee prices an output slightly below what a created address costs in storage,
+    // which is why a transfer paying a brand new address is charged a little more than its
+    // minimum required fee.
+    expect(NEW_ADDRESS_STORAGE_FEE).toBeGreaterThan(perOutput)
+  })
+})

package/tests/unit/Shielded.spec.ts

@@ -27,7 +27,9 @@ const ACCOUNT = 0
 // A funded testnet WIF reused across the builder/deposit tests.
 const WIF = 'cUy4wbim4y9NDwC24omx8oWY5WqfmjSU2gdcZtTXza2xDCAkQXRP'
 
-// Memo payloads are a fixed 32 bytes (MEMO_PAYLOAD_SIZE).
+// The memo payload field is a fixed 32 bytes (MEMO_PAYLOAD_SIZE) on the wire.
+// Text memos may be shorter and are zero-padded to it; `other` payloads are
+// taken verbatim and so must match it exactly.
 const MEMO_PAYLOAD_SIZE = 32
 
 const DASH = 100_000_000_000n
@@ -62,6 +64,7 @@ describe('ShieldedMemo', function () {
 
       expect(memo).toBeInstanceOf(ShieldedMemoWASM)
       expect(memo.toBytes().length).toEqual(36) // on-wire memo size
+      expect(memo.toString()).toEqual('')
     })
   })
 
@@ -72,11 +75,41 @@ describe('ShieldedMemo', function () {
 
       expect(memo).toBeInstanceOf(ShieldedMemoWASM)
       expect(memo.toBytes().length).toEqual(36)
-      expect(memo.toString().endsWith(text)).toBe(true)
+      expect(memo.toString()).toEqual(text)
     })
 
-    test('should reject a payload that is not 32 bytes', function () {
-      expect(() => ShieldedMemoWASM.fromString('too short')).toThrow()
+    test('should accept text shorter than the payload', function () {
+      const text = 'thanks for lunch' // 16 bytes, half the payload
+      const memo = ShieldedMemoWASM.fromString(text)
+      const bytes = memo.toBytes()
+
+      // The wire memo stays a fixed 36 bytes: a 4-byte little-endian kind tag
+      // (1 = text), the utf-8 text, then zero padding out to the 32-byte
+      // payload. The padding is not part of the decoded text.
+      expect(bytes.length).toEqual(36)
+      expect(Array.from(bytes.slice(0, 4))).toEqual([1, 0, 0, 0])
+      expect(new TextDecoder().decode(bytes.slice(4, 4 + text.length))).toEqual(text)
+      expect(bytes.slice(4 + text.length).every((byte) => byte === 0)).toBe(true)
+      expect(memo.toString()).toEqual(text)
+    })
+
+    test('should accept an empty string', function () {
+      const memo = ShieldedMemoWASM.fromString('')
+
+      expect(memo.toBytes().length).toEqual(36)
+      expect(memo.toString()).toEqual('')
+    })
+
+    test('should count multi-byte characters by their utf-8 byte length', function () {
+      // 8 x U+1F355 = 32 bytes, exactly the payload; 9 would be 36 bytes.
+      const memo = ShieldedMemoWASM.fromString('🍕'.repeat(8))
+
+      expect(memo.toString()).toEqual('🍕'.repeat(8))
+      expect(() => ShieldedMemoWASM.fromString('🍕'.repeat(9))).toThrow()
+    })
+
+    test('should reject text longer than 32 bytes', function () {
+      expect(() => ShieldedMemoWASM.fromString('A'.repeat(MEMO_PAYLOAD_SIZE + 1))).toThrow()
     })
   })