@fatsolutions/privacy-pools-core-starknet-sdk 0.0.40 → 0.0.42

package/src/account.service.ts

@@ -0,0 +1,42 @@
+import { AccountService, PoolAccount } from "@0xbow/privacy-pools-core-sdk";
+import { StarknetDataService } from "./data.service.js";
+import { AuditorData, deriveKeyFromMnemonic,packAuditorData, computeTag, encrypt } from "./auditor.js";
+import { base64 } from "@scure/base"
+
+type AccountServiceConfig = Exclude<ConstructorParameters<typeof AccountService>[1], {account:any}>
+
+export class StarknetAccountService extends AccountService {
+    private mnemonic: string;
+    constructor(dataService: StarknetDataService, config: AccountServiceConfig){ 
+        super(dataService as never, config);
+        this.mnemonic = config.mnemonic;
+    }
+
+    createAuditorData(
+        { label, deposit, children }: PoolAccount,
+        withdrawalValue?: bigint
+    ): {
+        auditorData: AuditorData;
+        withdrawalSecrets: ReturnType<StarknetAccountService['createWithdrawalSecrets']>;
+    } {
+        const viewKey = deriveKeyFromMnemonic(this.mnemonic, label);
+        const accountCommitment = children.at(-1) || deposit;
+        const withdrawalIndex = children.length;
+
+        const withdrawalSecrets = this.createWithdrawalSecrets(accountCommitment);
+
+        const packedData = packAuditorData({
+            value: withdrawalValue || accountCommitment.value,
+            label,
+            ...withdrawalSecrets,
+        });
+
+        const cipherArray = encrypt(packedData, viewKey);
+        const ciphertext = base64.encode(cipherArray);
+
+        const tag = computeTag(viewKey, withdrawalIndex);
+        const auditorData: AuditorData = { tag, ciphertext };
+        return { auditorData, withdrawalSecrets };
+    }
+}
+

package/src/auditor.ts

@@ -0,0 +1,223 @@
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha3_256 as sha256 } from "@noble/hashes/sha3.js";
+import { bytesToNumberBE, numberToBytesBE } from "@noble/ciphers/utils.js";
+import { Secret, getCommitment, AccountCommitment, Hash, PoolInfo } from "@0xbow/privacy-pools-core-sdk";
+import { CairoOption, CairoOptionVariant } from "starknet";
+import { poseidonHashMany } from "@scure/starknet";
+import { StarknetDataService } from "./data.service.js";
+import { base64 } from "@scure/base";
+import { mnemonicToEntropy } from "@scure/bip39";
+import { wordlist } from '@scure/bip39/wordlists/english';
+
+export interface AuditEvent {
+  tag: Hash;
+  ciphertext: string;
+  prevNullifierHash: Hash;
+  newCommitment: Hash;
+  blockNumber: bigint;
+  transactionHash: string;
+}
+
+//TODO: The first time you will need to generate a viewing key is in the first withdraw
+// of a deposited note. At that point you allready have a label. I suggest for the viewKey to be derivable
+// from the account secret + deposit label. There is no need to store another secret for each deposit.
+// viewKey =~ Hash(AccountSecret, Label);
+export function deriveKey(secret: Uint8Array, label: bigint): Uint8Array {
+  const info = new TextEncoder().encode("xchacha-key");
+  const salt = new TextEncoder().encode(String(label));
+  const viewKey = hkdf(sha256, secret, salt, info, 32);
+  return viewKey;
+}
+
+export function deriveKeyFromMnemonic(mnemonic: string, label: bigint): Uint8Array {
+  const secret = mnemonicToEntropy(mnemonic, wordlist);
+  return deriveKey(secret, label);
+}
+
+export function encrypt(plaintext: Uint8Array, viewKey: Uint8Array) {
+  const nonce = crypto.getRandomValues(new Uint8Array(24));
+
+  const chacha = xchacha20poly1305(viewKey, nonce);
+  const ciphertext = chacha.encrypt(plaintext);
+
+  // Prepend the nonce
+  const output = new Uint8Array(24 + ciphertext.length);
+  output.set(nonce, 0);
+  output.set(ciphertext, 24);
+
+  return output;
+}
+
+export function decrypt(input: Uint8Array, viewKey: Uint8Array): Uint8Array {
+  const nonce = input.slice(0, 24);
+  const chacha = xchacha20poly1305(viewKey, nonce);
+
+  const ciphertext = input.slice(24);
+  //TODO: What happens if AE fails?
+  const decrypted = chacha.decrypt(ciphertext);
+
+  return decrypted;
+}
+
+export function packAuditorData({
+  label: declaredLabel,
+  value: declaredValue,
+  nullifier: declaredNullifier,
+  secret: declaredSecret
+}: Pick<AccountCommitment, 'label' | 'value' | 'nullifier' | 'secret'>,
+): Uint8Array {
+
+  //TODO: Add assertions about lenght of bigint
+  const output = new Uint8Array(128);
+  output.set(numberToBytesBE(declaredLabel, 32), 0);
+  output.set(numberToBytesBE(declaredValue, 32), 32);
+  output.set(numberToBytesBE(declaredNullifier, 32), 64);
+  output.set(numberToBytesBE(declaredSecret, 32), 96);
+
+  return output;
+}
+
+export function unpackAuditorData(packedData: Uint8Array)
+  : {
+    declaredLabel: bigint,
+    declaredValue: bigint,
+    declaredNullifier: bigint,
+    declaredSecret: bigint;
+  } {
+  const declaredLabel = bytesToNumberBE(packedData.slice(0, 32));
+  const declaredValue = bytesToNumberBE(packedData.slice(32, 64));
+  const declaredNullifier = bytesToNumberBE(packedData.slice(64, 96));
+  const declaredSecret = bytesToNumberBE(packedData.slice(96, 128));
+
+  return { declaredLabel, declaredValue, declaredNullifier, declaredSecret };
+}
+
+
+export function reconstructAccountCommitment(event: AuditEvent, viewKey: Uint8Array): AccountCommitment {
+  const { ciphertext, blockNumber, transactionHash, prevNullifierHash } = event;
+
+  const auditorData = decrypt(base64.decode(ciphertext), viewKey);
+  const { declaredLabel, declaredValue, declaredNullifier, declaredSecret } = unpackAuditorData(auditorData);
+
+  const {
+    hash,
+    nullifierHash,
+    preimage: { value: _value, label, precommitment: _precommitment }
+  } = getCommitment(declaredValue, declaredLabel, declaredNullifier as Secret, declaredSecret as Secret);
+
+  if (nullifierHash != prevNullifierHash) {
+    throw new Error("Inconsistency in emitted nullifier hash");
+  }
+
+  return {
+    hash,
+    value: declaredValue,
+    label: label as Hash,
+    nullifier: declaredNullifier as Secret,
+    secret: declaredSecret as Secret,
+    blockNumber,
+    txHash: transactionHash as `0x{string}`,
+  };
+}
+
+export function computeTag(viewKey: Uint8Array, withdraw_number: number): bigint {
+  const viewKeyBigInt = bytesToNumberBE(viewKey);
+  const tag = poseidonHashMany([viewKeyBigInt, BigInt(withdraw_number)]);
+  return tag;
+};
+
+
+async function fetchAuditEventsForViewKey(
+  viewKey: Uint8Array,
+  serviceData: StarknetDataService,
+  pool: PoolInfo,
+): Promise<[AuditEvent, number][]> {
+  let out: [AuditEvent, number][] = [];
+  let withdraw_number = 0;
+  while (true) {
+    let tag = computeTag(viewKey, withdraw_number);
+    let events = await serviceData.getAuditEventForTag(tag, pool);
+    if (!events) { break; };
+
+    //It should be only ONE event with this tag. But it is not eforced. A troll could make a withdraw with 
+    //the tag of a previous withraw from another label.
+    events.forEach(event => out.push([event, withdraw_number]));
+    withdraw_number++;
+  }
+  return out;
+}
+
+export async function constructSequence(
+  viewKey: Uint8Array,
+  serviceData: StarknetDataService,
+  pool: PoolInfo
+): Promise<AccountCommitment[]> {
+  const commitments: AccountCommitment[] = [];
+  const events = await fetchAuditEventsForViewKey(viewKey, serviceData, pool);
+
+  const events_for_index = events.filter(([_, b]) => b === 0);
+  if (events_for_index.length === 0) {
+    throw new Error("No withdraws for this key");
+  }
+
+  let declaredCommitment: AccountCommitment | undefined;
+
+  for (const [event, _withdraw_number] of events_for_index) {
+    try {
+      declaredCommitment = reconstructAccountCommitment(event, viewKey);
+    } catch {
+      //What should we do here?
+    }
+  }
+
+  if (!declaredCommitment) {
+    throw new Error("No event could be decrypted");
+  }
+
+
+  let initialLabel = declaredCommitment.label;
+
+  let deposit = await serviceData.getDeposits(pool, pool.deploymentBlock, initialLabel);
+  if (deposit.length != 1) {
+    throw new Error("No deposit found for this label");
+  }
+
+  let initialCommitment = deposit[0]!.commitment;
+  if (initialCommitment != declaredCommitment.hash) {
+    throw new Error("mismatch");
+  }
+  commitments.push(declaredCommitment);
+
+  for (let i = 1; i < events.length; i++) {
+    let events_for_index = events.filter(([_, b]) => b === i);
+
+    for (const [event, _withdraw_number] of events_for_index) {
+      try {
+        declaredCommitment = reconstructAccountCommitment(event, viewKey);
+      } catch {
+        //What should we do here?
+      }
+    }
+
+    if (initialLabel != declaredCommitment.label) {
+      throw new Error("mismatch");
+    }
+
+    if (commitments[i - 1]!.hash != declaredCommitment.hash) {
+      throw new Error("mismatch");
+    }
+
+    commitments.push(declaredCommitment);
+  }
+
+  return commitments;
+}
+
+/**
+ * Represents a AuditEvent event from a privacy pool
+ */
+export interface AuditorData {
+  tag: bigint;
+  ciphertext: string;
+}

package/src/contracts/contracts.service.ts

@@ -8,7 +8,7 @@ import { ETH_ADDRESS } from "../constants.js";
 import { SNContractError, SNPoolError, StarknetSDKError } from "../errors/index.js";
 import { AssetConfig, Withdrawal } from "../types/entrypoint.js";
 import { StarknetAddress } from "../types/starknet.js";
-import { castBigInt, toAddress } from "../utils.js";
+import { castBigInt, toAddress, toCairoOption } from "../utils.js";
 import { executeIntent, simulateIntent } from "./transactionHandler.js";
 
 /**
@@ -251,8 +251,9 @@ export class SNContractInteractionsService {
    */
   withdraw(withdrawal: Withdrawal, withdrawalProofGaraga: bigint[], scope: Hash, options: OptionModeExecute): Promise<InvokeFunctionResponse>;
   async withdraw(withdrawal: Withdrawal, withdrawalProofGaraga: bigint[], scope: Hash, options?: OptionModes): Promise<CallResult> {
+    const _withdrawal = { ...withdrawal, auditorData: toCairoOption(withdrawal.auditorData) };
     const { poolAddress } = await this.getScopeData(scope);
-    const call = this.pool(poolAddress).populate("withdraw", [withdrawal, { fullProof: withdrawalProofGaraga }]);
+    const call = this.pool(poolAddress).populate("withdraw", [_withdrawal, { fullProof: withdrawalProofGaraga }]);
     return _intentOptionWrapper(call, options && { ...options, account: this.providerOrAccount });
   }
 
@@ -286,7 +287,8 @@ export class SNContractInteractionsService {
    */
   relay(withdrawal: Withdrawal, withdrawalProofGaraga: bigint[], scope: Hash, options: OptionModeExecute): Promise<InvokeFunctionResponse>;
   relay(withdrawal: Withdrawal, withdrawalProofGaraga: bigint[], scope: Hash, options?: OptionModes): Promise<CallResult> {
-    const call = this.entrypoint.populate("relay", [withdrawal, scope, { fullProof: withdrawalProofGaraga }]);
+    const _withdrawal = { ...withdrawal, auditorData: toCairoOption(withdrawal.auditorData) };
+    const call = this.entrypoint.populate("relay", [_withdrawal, scope, { fullProof: withdrawalProofGaraga }]);
     return _intentOptionWrapper(call, options && { ...options, account: this.providerOrAccount });
   }
 

package/src/data.service.ts

@@ -5,6 +5,7 @@ import {
   RagequitEvent,
   WithdrawalEvent,
 } from "@0xbow/privacy-pools-core-sdk";
+import { AuditEvent } from "./auditor.js"
 import {
   AbiParser2,
   EmittedEvent,
@@ -21,6 +22,7 @@ import {
   StarknetSDKError,
 } from "./errors/index.js";
 
+
 // Calculate event selectors using Starknet keccak
 export const DEPOSIT_EVENT_SELECTOR = num.toHex(
   hash.starknetKeccak("Deposited")
@@ -32,15 +34,21 @@ export const RAGEQUIT_EVENT_SELECTOR = num.toHex(
   hash.starknetKeccak("RageQuit")
 ); // 0x2a2469e4569da9d3c3df9bc1a2ddece1e640a89b8ecd537da96f064d64c8183
 
+export const AUDIT_EVENT_SELECTOR = num.toHex(
+  hash.starknetKeccak("AuditEvent")
+);
+
 // ABI event names for direct selection
 export const DEPOSIT_EVENT_ABI_NAME = "privacy_pools::interfaces::IPool::Deposited";
 export const WITHDRAWAL_EVENT_ABI_NAME = "privacy_pools::interfaces::IPool::Withdrawn";
 export const RAGEQUIT_EVENT_ABI_NAME = "privacy_pools::interfaces::IPool::RageQuit";
+export const AUDIT_EVENT_ABI_NAME = "privacy_pools::interfaces::IPool::AuditEvent";
 
 export const AbiEventName = {
   Deposit: DEPOSIT_EVENT_ABI_NAME,
   Withdraw: WITHDRAWAL_EVENT_ABI_NAME,
   Ragequit: RAGEQUIT_EVENT_ABI_NAME,
+  Audit: AUDIT_EVENT_ABI_NAME,
 } as const;
 
 type AbiEventName = (typeof AbiEventName)[keyof typeof AbiEventName];
@@ -59,6 +67,7 @@ export interface StarknetWithdrawnEventData {
   newCommitmentHash: bigint;
   withdrawnValue: bigint;
   existingNullifierHash: bigint;
+  auditorData: string;
 }
 
 export interface StarknetRageQuitEventData {
@@ -68,15 +77,24 @@ export interface StarknetRageQuitEventData {
   value: bigint;
 }
 
+export interface StarknetAuditEventData {
+    tag: bigint;
+    ciphertext:string;
+    prevNullifierHash: bigint,
+    newCommitment: bigint,
+}
+
 type AbiToEvent = {
   [AbiEventName.Deposit]: StarknetDepositedEventData;
   [AbiEventName.Withdraw]: StarknetWithdrawnEventData;
   [AbiEventName.Ragequit]: StarknetRageQuitEventData;
+  [AbiEventName.Audit]: StarknetAuditEventData;
 };
 
 export type StarknetEvent =
   | StarknetDepositedEventData
   | StarknetWithdrawnEventData
+  | StarknetAuditEventData
   | StarknetRageQuitEventData;
 
 /**
@@ -123,15 +141,17 @@ export class StarknetDataService {
    */
   async getDeposits(
     pool: PoolInfo,
-    fromBlock: bigint = pool.deploymentBlock
+    fromBlock: bigint = pool.deploymentBlock,
+    label?: bigint,
   ): Promise<DepositEvent[]> {
     try {
+      const keys = label? [[DEPOSIT_EVENT_SELECTOR],[],[String(label)]] : [[DEPOSIT_EVENT_SELECTOR]];
       // Fetch events using Starknet provider
       const eventsResult = await this.getEvents({
         from_block: { block_number: Number(fromBlock) },
         to_block: "latest",
         address: pool.address,
-        keys: [[DEPOSIT_EVENT_SELECTOR]], // Filter by deposit event selector
+        keys, // Filter by deposit event selector
         chunk_size: 1000, // Starknet pagination
       });
 
@@ -293,6 +313,63 @@ export class StarknetDataService {
             transactionHash: transactionHash || "0x0",
           } as RagequitEvent)
         );
+        // PARSEAR
+    } catch (error) {
+      if (error instanceof StarknetSDKError) throw error;
+      throw new StarknetSDKError(
+        `Failed to fetch ragequits: ${error instanceof Error ? error.message : "Unknown error"
+        }`,
+        SNBaseErrorCode.UNKNOWN
+      );
+    }
+  }
+
+  async getAuditEventForTag(
+    tag: bigint,
+    pool: PoolInfo,
+    fromBlock: bigint = pool.deploymentBlock
+  ) {
+    try {
+      const eventsResult = await this.getEvents({
+        from_block: { block_number: Number(fromBlock) },
+        to_block: "latest",
+        address: pool.address,
+        keys: [[AUDIT_EVENT_SELECTOR], [String(tag)]],
+        chunk_size: 1000,
+      });
+
+      // Parse all events at once using starknet.js event parser
+      const abiEvents = events.getAbiEvents(PrivacyPoolABI);
+      const parsedEvents = events.parseEvents(
+        eventsResult,
+        abiEvents,
+        {},
+        {},
+        this.abiParser
+      );
+
+      return parsedEvents
+        .filter(
+          (parsedEvent) => parsedEvent[AUDIT_EVENT_ABI_NAME] !== undefined
+        )
+        .map((parsedEvent) => ({
+          eventData: parsedEvent[
+            AUDIT_EVENT_ABI_NAME
+          ] as unknown as StarknetAuditEventData,
+          blockNumber: parsedEvent.block_number,
+          transactionHash: parsedEvent.transaction_hash,
+        }))
+        .map(
+          ({ eventData, blockNumber, transactionHash }) =>
+          ({
+            tag: eventData.tag as Hash,
+            ciphertext: eventData.ciphertext,
+            prevNullifierHash: eventData.prevNullifierHash as Hash,
+            newCommitment: eventData.newCommitment as Hash,
+            blockNumber: BigInt(blockNumber || 0),
+            transactionHash: transactionHash || "0x0",
+          } as AuditEvent)
+        );
     } catch (error) {
       if (error instanceof StarknetSDKError) throw error;
       throw new StarknetSDKError(

package/src/index.ts

@@ -85,3 +85,8 @@ export {
 } from "./data.service.js";
 
 export { type StarknetAddress } from "./types/starknet.js";
+
+// Auditor
+export * from "./auditor.js";
+
+export * from './account.service.js';

package/src/types/entrypoint.ts

@@ -1,8 +1,9 @@
-import { BigNumberish, cairo, CallData, num } from "starknet";
+import { BigNumberish, cairo, CallData, num, CairoOption, byteArray } from "starknet";
 
 import { EntryPointABI } from "../abis/index.js";
 import { SNFormatError } from "../errors/index.js";
 import { StarknetAddress } from "./starknet.js";
+import { AuditorData } from "../auditor.js";
 
 const RelayDataAbi = [
   {
@@ -46,6 +47,7 @@ const entrypointCd = new CallData(EntryPointABI);
 export interface Withdrawal {
   /** The address of the processor handling this withdrawal */
   processor: BigNumberish,
+  auditorData?: AuditorData;
   /** Additional data required for processing the withdrawal */
   data: BigNumberish[];
 }
@@ -113,18 +115,48 @@ export function parseRelayData(rawData: string[]): RelayData {
  * @returns Array of string representations of the withdrawal fields
  */
 export function serializeWithdrawal(withdrawal: Withdrawal): `0x${string}`[] {
-  const { processor, data } = withdrawal;
-  return [
-    num.toHex64(processor) as `0x${string}`,
-    num.toHex64(data.length) as `0x${string}`,
-    ...data.map(x => num.toHex64(x) as `0x${string}`)
-  ];
+  let result: `0x${string}`[] = [];
+  const { processor, auditorData, data } = withdrawal;
+
+  result.push(num.toHex64(processor) as `0x${string}`);
+
+  if (auditorData === undefined) {
+    result.push(num.toHex64(1) as `0x${string}`);
+  } else {
+    result.push(num.toHex64(0) as `0x${string}`);
+    const { tag, ciphertext } = auditorData;
+    const { low, high } = cairo.uint256(tag);
+    result.push(num.toHex64(low) as `0x${string}`);
+    result.push(num.toHex64(high) as `0x${string}`);
+
+    const array = CallData.compile([byteArray.byteArrayFromString(ciphertext)]);
+    array.forEach((x) => result.push(num.toHex64(x) as `0x${string}`));
+  }
+
+  result.push(num.toHex64(data.length) as `0x${string}`);
+  data.forEach((x) => result.push(num.toHex64(x) as `0x${string}`));
+  return result;
 }
 
-function isWithdrawal(data: unknown): data is Withdrawal {
-  const _data = data as Withdrawal;
-  return (_data.processor !== undefined && num.isBigNumberish(_data.processor))
-    && (_data.data !== undefined && _data.data.every(num.isBigNumberish));
+type CairoWithdrawal = {
+  processor: BigNumberish;
+  data: BigNumberish[];
+  auditorData: CairoOption<AuditorData>;
+};
+function isWithdrawal(data: unknown): data is CairoWithdrawal {
+  const _data = data as CairoWithdrawal;
+  return (
+    _data.processor !== undefined &&
+    num.isBigNumberish(_data.processor)
+  ) && (
+      _data.data !== undefined &&
+      _data.data.every(num.isBigNumberish)
+    ) && (
+      (
+        _data.auditorData.Some?.ciphertext !== undefined &&
+        _data.auditorData.Some?.tag !== undefined
+      ) || _data.auditorData.None !== undefined
+    );
 }
 
 /**
@@ -140,7 +172,8 @@ export function parseWithdrawal(rawData: string[]): Withdrawal {
   }
   const structName = "privacy_pools::interfaces::Structs::Withdrawal";
   const result = entrypointCd.decodeParameters(structName, rawData);
-  if (isWithdrawal(result))
-    return result;
+  if (isWithdrawal(result)) {
+    return { ...result, auditorData: result.auditorData.unwrap() };
+  }
   throw SNFormatError.parse(`Can't parse Withdrawal from ${rawData}`);
 }

package/src/utils.ts

@@ -1,6 +1,6 @@
 import { WithdrawalProof } from "@0xbow/privacy-pools-core-sdk";
 import { poseidonHashMany } from "@scure/starknet";
-import { BigNumberish, cairo, num, uint256, Uint256, validateAndParseAddress, validateChecksumAddress } from "starknet";
+import { BigNumberish, cairo, CairoOption, CairoOptionVariant, num, uint256, Uint256, validateAndParseAddress, validateChecksumAddress } from "starknet";
 
 import { getGroth16CallData } from "./garaga.js";
 import { snarkJsKeyIntoGaraga, snarkJsProofIntoGaraga } from "./types/conversions.js";
@@ -94,3 +94,15 @@ export function castBigInt(x: number | bigint | Uint256) {
 export function toAddress(x: BigNumberish): StarknetAddress {
   return validateAndParseAddress(x) as StarknetAddress;
 }
+
+export const Some = <T>(t: T): CairoOption<T> => {
+  return new CairoOption<T>(CairoOptionVariant.Some, t);
+};
+
+export const None = <T>(): CairoOption<T> => {
+  return new CairoOption<T>(CairoOptionVariant.None);
+};
+
+export const toCairoOption = <T>(t?: T): CairoOption<T> => {
+  return t === undefined ? None() : Some(t);
+};