@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/kernel/private_to_rollup_kernel_circuit_public_inputs.ts

@@ -0,0 +1,112 @@
+import { GeneratorIndex, PRIVATE_TO_ROLLUP_KERNEL_CIRCUIT_PUBLIC_INPUTS_LENGTH } from '@aztec/constants';
+import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto';
+import type { Fr } from '@aztec/foundation/fields';
+import { bufferSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import { Gas } from '../gas/gas.js';
+import { TxConstantData } from '../tx/tx_constant_data.js';
+import { RollupValidationRequests } from './hints/rollup_validation_requests.js';
+import { PrivateToRollupAccumulatedData } from './private_to_rollup_accumulated_data.js';
+
+/**
+ * Outputs from the public kernel circuits.
+ * All Public kernels use this shape for outputs.
+ */
+export class PrivateToRollupKernelCircuitPublicInputs {
+  constructor(
+    /**
+     * Data which is not modified by the circuits.
+     */
+    public constants: TxConstantData,
+    /**
+     * Validation requests accumulated from private and public execution to be completed by the rollup.
+     */
+    public rollupValidationRequests: RollupValidationRequests,
+    /**
+     * Data accumulated from both public and private circuits.
+     */
+    public end: PrivateToRollupAccumulatedData,
+    /**
+     * Gas used during this transaction
+     */
+    public gasUsed: Gas,
+    /**
+     * The address of the fee payer for the transaction.
+     */
+    public feePayer: AztecAddress,
+  ) {}
+
+  getNonEmptyNullifiers() {
+    return this.end.nullifiers.filter(n => !n.isZero());
+  }
+
+  toBuffer() {
+    return serializeToBuffer(this.constants, this.rollupValidationRequests, this.end, this.gasUsed, this.feePayer);
+  }
+
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer or reader to read from.
+   * @returns A new instance of PrivateToRollupKernelCircuitPublicInputs.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): PrivateToRollupKernelCircuitPublicInputs {
+    const reader = BufferReader.asReader(buffer);
+    return new PrivateToRollupKernelCircuitPublicInputs(
+      reader.readObject(TxConstantData),
+      reader.readObject(RollupValidationRequests),
+      reader.readObject(PrivateToRollupAccumulatedData),
+      reader.readObject(Gas),
+      reader.readObject(AztecAddress),
+    );
+  }
+
+  static empty() {
+    return new PrivateToRollupKernelCircuitPublicInputs(
+      TxConstantData.empty(),
+      RollupValidationRequests.empty(),
+      PrivateToRollupAccumulatedData.empty(),
+      Gas.empty(),
+      AztecAddress.ZERO,
+    );
+  }
+
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  static fromString(str: string) {
+    return PrivateToRollupKernelCircuitPublicInputs.fromBuffer(hexToBuffer(str));
+  }
+
+  /** Returns a hex representation for JSON serialization. */
+  toJSON() {
+    return this.toBuffer();
+  }
+
+  static getFields(fields: FieldsOf<PrivateToRollupKernelCircuitPublicInputs>) {
+    return [fields.constants, fields.rollupValidationRequests, fields.end, fields.gasUsed, fields.feePayer] as const;
+  }
+
+  /** Creates an instance from a hex string. */
+  static get schema() {
+    return bufferSchemaFor(PrivateToRollupKernelCircuitPublicInputs);
+  }
+
+  toFields(): Fr[] {
+    const fields = serializeToFields(...PrivateToRollupKernelCircuitPublicInputs.getFields(this));
+    if (fields.length !== PRIVATE_TO_ROLLUP_KERNEL_CIRCUIT_PUBLIC_INPUTS_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for PrivateToRollupKernelCircuitPublicInputs. Expected ${PRIVATE_TO_ROLLUP_KERNEL_CIRCUIT_PUBLIC_INPUTS_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  hash() {
+    return poseidon2HashWithSeparator(this.toFields(), GeneratorIndex.PRIVATE_TX_HASH);
+  }
+}

package/src/kernel/private_validation_requests.ts

@@ -0,0 +1,140 @@
+import {
+  MAX_KEY_VALIDATION_REQUESTS_PER_TX,
+  MAX_NOTE_HASH_READ_REQUESTS_PER_TX,
+  MAX_NULLIFIER_READ_REQUESTS_PER_TX,
+} from '@aztec/constants';
+import { makeTuple } from '@aztec/foundation/array';
+import { arraySerializedSizeOfNonEmpty } from '@aztec/foundation/collection';
+import type { Fr } from '@aztec/foundation/fields';
+import { BufferReader, FieldReader, type Tuple, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+
+import { inspect } from 'util';
+
+import { ScopedKeyValidationRequestAndGenerator } from '../kernel/hints/scoped_key_validation_request_and_generator.js';
+import { ScopedReadRequest } from './hints/read_request.js';
+import { RollupValidationRequests } from './hints/rollup_validation_requests.js';
+import { OptionalNumber } from './utils/optional_number.js';
+
+/**
+ * Validation requests accumulated during the execution of the transaction.
+ */
+export class PrivateValidationRequests {
+  constructor(
+    /**
+     * Validation requests that cannot be fulfilled in the current context (private or public), and must be instead be
+     * forwarded to the rollup for it to take care of them.
+     */
+    public forRollup: RollupValidationRequests,
+    /**
+     * All the read requests made in this transaction.
+     */
+    public noteHashReadRequests: Tuple<ScopedReadRequest, typeof MAX_NOTE_HASH_READ_REQUESTS_PER_TX>,
+    /**
+     * All the nullifier read requests made in this transaction.
+     */
+    public nullifierReadRequests: Tuple<ScopedReadRequest, typeof MAX_NULLIFIER_READ_REQUESTS_PER_TX>,
+    /**
+     * All the key validation requests made in this transaction.
+     */
+    public scopedKeyValidationRequestsAndGenerators: Tuple<
+      ScopedKeyValidationRequestAndGenerator,
+      typeof MAX_KEY_VALIDATION_REQUESTS_PER_TX
+    >,
+    /**
+     * The counter to split the data for squashing.
+     * A revertible nullifier and a non-revertible note hash will not be squashed.
+     * It should be the "final" minRevertibleSideEffectCounter of a tx.
+     */
+    public splitCounter: OptionalNumber,
+  ) {}
+
+  getSize() {
+    return (
+      this.forRollup.getSize() +
+      arraySerializedSizeOfNonEmpty(this.noteHashReadRequests) +
+      arraySerializedSizeOfNonEmpty(this.nullifierReadRequests) +
+      arraySerializedSizeOfNonEmpty(this.scopedKeyValidationRequestsAndGenerators) +
+      this.splitCounter.getSize()
+    );
+  }
+
+  toBuffer() {
+    return serializeToBuffer(
+      this.forRollup,
+      this.noteHashReadRequests,
+      this.nullifierReadRequests,
+      this.scopedKeyValidationRequestsAndGenerators,
+      this.splitCounter,
+    );
+  }
+
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return new PrivateValidationRequests(
+      reader.readObject(RollupValidationRequests),
+      reader.readArray(MAX_NOTE_HASH_READ_REQUESTS_PER_TX, ScopedReadRequest),
+      reader.readArray(MAX_NULLIFIER_READ_REQUESTS_PER_TX, ScopedReadRequest),
+      reader.readArray(MAX_KEY_VALIDATION_REQUESTS_PER_TX, ScopedKeyValidationRequestAndGenerator),
+      reader.readObject(OptionalNumber),
+    );
+  }
+
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer or reader to read from.
+   * @returns Deserialized object.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new PrivateValidationRequests(
+      reader.readObject(RollupValidationRequests),
+      reader.readArray(MAX_NOTE_HASH_READ_REQUESTS_PER_TX, ScopedReadRequest),
+      reader.readArray(MAX_NULLIFIER_READ_REQUESTS_PER_TX, ScopedReadRequest),
+      reader.readArray(MAX_KEY_VALIDATION_REQUESTS_PER_TX, ScopedKeyValidationRequestAndGenerator),
+      reader.readObject(OptionalNumber),
+    );
+  }
+
+  /**
+   * Deserializes from a string, corresponding to a write in cpp.
+   * @param str - String to read from.
+   * @returns Deserialized object.
+   */
+  static fromString(str: string) {
+    return PrivateValidationRequests.fromBuffer(hexToBuffer(str));
+  }
+
+  static empty() {
+    return new PrivateValidationRequests(
+      RollupValidationRequests.empty(),
+      makeTuple(MAX_NOTE_HASH_READ_REQUESTS_PER_TX, ScopedReadRequest.empty),
+      makeTuple(MAX_NULLIFIER_READ_REQUESTS_PER_TX, ScopedReadRequest.empty),
+      makeTuple(MAX_KEY_VALIDATION_REQUESTS_PER_TX, ScopedKeyValidationRequestAndGenerator.empty),
+      OptionalNumber.empty(),
+    );
+  }
+
+  [inspect.custom]() {
+    return `PrivateValidationRequests {
+  forRollup: ${inspect(this.forRollup)},
+  noteHashReadRequests: [${this.noteHashReadRequests
+    .filter(x => !x.isEmpty())
+    .map(h => inspect(h))
+    .join(', ')}],
+  nullifierReadRequests: [${this.nullifierReadRequests
+    .filter(x => !x.isEmpty())
+    .map(h => inspect(h))
+    .join(', ')}],
+  scopedKeyValidationRequestsAndGenerators: [${this.scopedKeyValidationRequestsAndGenerators
+    .filter(x => !x.isEmpty())
+    .map(h => inspect(h))
+    .join(', ')}],
+  splitCounter: ${this.splitCounter}
+  `;
+  }
+}

package/src/kernel/public_call_request.ts

@@ -0,0 +1,157 @@
+import { COUNTED_PUBLIC_CALL_REQUEST_LENGTH, PUBLIC_CALL_REQUEST_LENGTH } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { inspect } from 'util';
+
+import { FunctionSelector } from '../abi/index.js';
+import { AztecAddress } from '../aztec-address/index.js';
+import type { UInt32 } from '../types/shared.js';
+
+/**
+ * Represents a request to call a public function.
+ */
+export class PublicCallRequest {
+  constructor(
+    /**
+     * Address of the account which represents the entity who invoked the call.
+     */
+    public msgSender: AztecAddress,
+    /**
+     * The contract address being called.
+     */
+    public contractAddress: AztecAddress,
+    /**
+     * Function selector of the function being called.
+     */
+    public functionSelector: FunctionSelector,
+    /**
+     * Determines whether the call is modifying state.
+     */
+    public isStaticCall: boolean,
+    public argsHash: Fr,
+  ) {}
+
+  getSize() {
+    return this.isEmpty() ? 0 : this.toBuffer().length;
+  }
+
+  static from(fields: FieldsOf<PublicCallRequest>): PublicCallRequest {
+    return new PublicCallRequest(...PublicCallRequest.getFields(fields));
+  }
+
+  static getFields(fields: FieldsOf<PublicCallRequest>) {
+    return [
+      fields.msgSender,
+      fields.contractAddress,
+      fields.functionSelector,
+      fields.isStaticCall,
+      fields.argsHash,
+    ] as const;
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): PublicCallRequest {
+    const reader = FieldReader.asReader(fields);
+    return new PublicCallRequest(
+      reader.readObject(AztecAddress),
+      reader.readObject(AztecAddress),
+      reader.readObject(FunctionSelector),
+      reader.readBoolean(),
+      reader.readField(),
+    );
+  }
+
+  toFields(): Fr[] {
+    const fields = serializeToFields(...PublicCallRequest.getFields(this));
+    if (fields.length !== PUBLIC_CALL_REQUEST_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for PublicCallRequest. Expected ${PUBLIC_CALL_REQUEST_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new PublicCallRequest(
+      reader.readObject(AztecAddress),
+      reader.readObject(AztecAddress),
+      reader.readObject(FunctionSelector),
+      reader.readBoolean(),
+      reader.readObject(Fr),
+    );
+  }
+
+  toBuffer() {
+    return serializeToBuffer(...PublicCallRequest.getFields(this));
+  }
+
+  static empty() {
+    return new PublicCallRequest(AztecAddress.ZERO, AztecAddress.ZERO, FunctionSelector.empty(), false, Fr.ZERO);
+  }
+
+  isEmpty(): boolean {
+    return (
+      this.msgSender.isZero() &&
+      this.contractAddress.isZero() &&
+      this.functionSelector.isEmpty() &&
+      !this.isStaticCall &&
+      this.argsHash.isEmpty()
+    );
+  }
+
+  [inspect.custom]() {
+    return `PublicCallRequest {
+      msgSender: ${this.msgSender}
+      contractAddress: ${this.contractAddress}
+      functionSelector: ${this.functionSelector}
+      isStaticCall: ${this.isStaticCall}
+      argsHash: ${this.argsHash}
+    }`;
+  }
+}
+
+export class CountedPublicCallRequest {
+  constructor(public inner: PublicCallRequest, public counter: UInt32) {}
+
+  getSize() {
+    return this.isEmpty() ? 0 : this.toBuffer().length;
+  }
+
+  static getFields(fields: FieldsOf<CountedPublicCallRequest>) {
+    return [fields.inner, fields.counter] as const;
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return new CountedPublicCallRequest(reader.readObject(PublicCallRequest), reader.readU32());
+  }
+
+  toFields(): Fr[] {
+    const fields = serializeToFields(...CountedPublicCallRequest.getFields(this));
+    if (fields.length !== COUNTED_PUBLIC_CALL_REQUEST_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for CountedPublicCallRequest. Expected ${COUNTED_PUBLIC_CALL_REQUEST_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new CountedPublicCallRequest(reader.readObject(PublicCallRequest), reader.readNumber());
+  }
+
+  toBuffer() {
+    return serializeToBuffer(...CountedPublicCallRequest.getFields(this));
+  }
+
+  static empty() {
+    return new CountedPublicCallRequest(PublicCallRequest.empty(), 0);
+  }
+
+  isEmpty(): boolean {
+    return this.inner.isEmpty() && this.counter == 0;
+  }
+}

package/src/kernel/utils/index.ts

@@ -0,0 +1,3 @@
+export * from './interfaces.js';
+export * from './optional_number.js';
+export * from './order_and_comparison.js';

package/src/kernel/utils/interfaces.ts

@@ -0,0 +1,7 @@
+export interface IsEmpty {
+  isEmpty: () => boolean;
+}
+
+export interface Ordered {
+  counter: number;
+}

package/src/kernel/utils/optional_number.ts

@@ -0,0 +1,50 @@
+import type { Fr } from '@aztec/foundation/fields';
+import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+export class OptionalNumber {
+  constructor(
+    /**
+     * Whether a value was set.
+     */
+    public isSome: boolean,
+    /**
+     * The actual number, if isSome is true.
+     */
+    public value: number,
+  ) {}
+
+  getSize() {
+    return this.toBuffer().length;
+  }
+
+  static getFields(fields: FieldsOf<OptionalNumber>) {
+    return [fields.isSome, fields.value] as const;
+  }
+
+  toBuffer() {
+    return serializeToBuffer(...OptionalNumber.getFields(this));
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): OptionalNumber {
+    const reader = BufferReader.asReader(buffer);
+    return new OptionalNumber(reader.readBoolean(), reader.readNumber());
+  }
+
+  toFields(): Fr[] {
+    return serializeToFields(...OptionalNumber.getFields(this));
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): OptionalNumber {
+    const reader = FieldReader.asReader(fields);
+    return new OptionalNumber(reader.readBoolean(), reader.readU32());
+  }
+
+  isEmpty(): boolean {
+    return !this.isSome && !this.value;
+  }
+
+  static empty() {
+    return new OptionalNumber(false, 0);
+  }
+}

package/src/kernel/utils/order_and_comparison.ts

@@ -0,0 +1,71 @@
+import type { Tuple } from '@aztec/foundation/serialize';
+
+import type { IsEmpty, Ordered } from './interfaces.js';
+
+// Define these utils here as their design is very specific to kernel's accumulated data and not general enough to be put in foundation.
+
+// Returns number of non-empty items in an array.
+export function countAccumulatedItems<T extends IsEmpty>(arr: T[]) {
+  return arr.reduce((num, item, i) => {
+    if (!item.isEmpty()) {
+      if (num !== i) {
+        throw new Error('Non-empty items must be placed continuously from index 0.');
+      }
+      return num + 1;
+    }
+    return num;
+  }, 0);
+}
+
+// Merges two arrays of length N into an array of length N.
+export function mergeAccumulatedData<T extends IsEmpty, N extends number>(
+  arr0: Tuple<T, N>,
+  arr1: Tuple<T, N>,
+  length: N = arr0.length as N, // Need this for ts to infer the return Tuple length.
+): Tuple<T, N> {
+  const numNonEmptyItems0 = countAccumulatedItems(arr0);
+  const numNonEmptyItems1 = countAccumulatedItems(arr1);
+  if (numNonEmptyItems0 + numNonEmptyItems1 > length) {
+    throw new Error('Combined non-empty items exceeded the maximum allowed.');
+  }
+
+  const arr = [...arr0] as Tuple<T, N>;
+  arr1.slice(0, numNonEmptyItems1).forEach((item, i) => (arr[i + numNonEmptyItems0] = item));
+  return arr;
+}
+
+// Sort items by a provided compare function. All empty items are padded to the right.
+function genericSort<T extends IsEmpty, N extends number>(
+  arr: Tuple<T, N>,
+  compareFn: (a: T, b: T) => number,
+  ascending: boolean = true,
+): Tuple<T, N> {
+  return [...arr].sort((a, b) => {
+    if (a.isEmpty()) {
+      return 1; // Move empty items to the right.
+    }
+    if (b.isEmpty()) {
+      return -1; // Move non-empty items to the left.
+    }
+    return ascending ? compareFn(a, b) : compareFn(b, a);
+  }) as Tuple<T, N>;
+}
+
+function compareByCounter<T extends Ordered>(a: T, b: T): number {
+  return a.counter - b.counter;
+}
+
+export function sortByCounter<T extends Ordered & IsEmpty, N extends number>(
+  arr: Tuple<T, N>,
+  ascending: boolean = true,
+): Tuple<T, N> {
+  return genericSort(arr, compareByCounter, ascending);
+}
+
+export function isEmptyArray<T extends IsEmpty>(arr: T[]): boolean {
+  return arr.every(item => item.isEmpty());
+}
+
+export function getNonEmptyItems<T extends IsEmpty>(arr: T[]): T[] {
+  return arr.filter(item => !item.isEmpty());
+}

package/src/keys/derivation.ts

@@ -0,0 +1,141 @@
+import { GeneratorIndex } from '@aztec/constants';
+import { Grumpkin, poseidon2HashWithSeparator, sha512ToGrumpkinScalar } from '@aztec/foundation/crypto';
+import { Fq, Fr, GrumpkinScalar } from '@aztec/foundation/fields';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import type { CompleteAddress } from '../contract/complete_address.js';
+import type { KeyPrefix } from './key_types.js';
+import { PublicKeys } from './public_keys.js';
+import { getKeyGenerator } from './utils.js';
+
+export function computeAppNullifierSecretKey(masterNullifierSecretKey: GrumpkinScalar, app: AztecAddress): Promise<Fr> {
+  return computeAppSecretKey(masterNullifierSecretKey, app, 'n'); // 'n' is the key prefix for nullifier secret key
+}
+
+export function computeAppSecretKey(skM: GrumpkinScalar, app: AztecAddress, keyPrefix: KeyPrefix): Promise<Fr> {
+  const generator = getKeyGenerator(keyPrefix);
+  return poseidon2HashWithSeparator([skM.hi, skM.lo, app], generator);
+}
+
+export async function computeOvskApp(ovsk: GrumpkinScalar, app: AztecAddress): Promise<Fq> {
+  const ovskAppFr = await computeAppSecretKey(ovsk, app, 'ov'); // 'ov' is the key prefix for outgoing viewing key
+  // Here we are intentionally converting Fr (output of poseidon) to Fq. This is fine even though a distribution of
+  // P = s * G will not be uniform because 2 * (q - r) / q is small.
+  return GrumpkinScalar.fromBuffer(ovskAppFr.toBuffer());
+}
+
+export function deriveMasterNullifierSecretKey(secretKey: Fr): GrumpkinScalar {
+  return sha512ToGrumpkinScalar([secretKey, GeneratorIndex.NSK_M]);
+}
+
+export function deriveMasterIncomingViewingSecretKey(secretKey: Fr): GrumpkinScalar {
+  return sha512ToGrumpkinScalar([secretKey, GeneratorIndex.IVSK_M]);
+}
+
+export function deriveMasterOutgoingViewingSecretKey(secretKey: Fr): GrumpkinScalar {
+  return sha512ToGrumpkinScalar([secretKey, GeneratorIndex.OVSK_M]);
+}
+
+export function deriveSigningKey(secretKey: Fr): GrumpkinScalar {
+  // TODO(#5837): come up with a standard signing key derivation scheme instead of using ivsk_m as signing keys here
+  return sha512ToGrumpkinScalar([secretKey, GeneratorIndex.IVSK_M]);
+}
+
+export function computePreaddress(publicKeysHash: Fr, partialAddress: Fr) {
+  return poseidon2HashWithSeparator([publicKeysHash, partialAddress], GeneratorIndex.CONTRACT_ADDRESS_V1);
+}
+
+export async function computeAddress(publicKeys: PublicKeys, partialAddress: Fr): Promise<AztecAddress> {
+  // Given public keys and a partial address, we can compute our address in the following steps.
+  // 1. preaddress = poseidon2([publicKeysHash, partialAddress], GeneratorIndex.CONTRACT_ADDRESS_V1);
+  // 2. addressPoint = (preaddress * G) + ivpk_m
+  // 3. address = addressPoint.x
+  const preaddress = await computePreaddress(await publicKeys.hash(), partialAddress);
+  const address = await new Grumpkin().add(
+    await derivePublicKeyFromSecretKey(new Fq(preaddress.toBigInt())),
+    publicKeys.masterIncomingViewingPublicKey,
+  );
+
+  return new AztecAddress(address.x);
+}
+
+export async function computeAddressSecret(preaddress: Fr, ivsk: Fq) {
+  // TLDR; P1 = (h + ivsk) * G
+  // if P1.y is pos
+  //   S = (h + ivsk)
+  // else
+  //   S = Fq.MODULUS - (h + ivsk)
+  //
+  // Given h (our preaddress) and our ivsk, we have two different addressSecret candidates. One encodes to a point with a positive y-coordinate
+  // and the other encodes to a point with a negative y-coordinate. We take the addressSecret candidate that is a simple addition of the two Scalars.
+  const addressSecretCandidate = ivsk.add(new Fq(preaddress.toBigInt()));
+  // We then multiply this secretCandidate by the generator G to create an addressPoint candidate.
+  const addressPointCandidate = await derivePublicKeyFromSecretKey(addressSecretCandidate);
+
+  // Because all encryption to addresses is done using a point with the positive y-coordinate, if our addressSecret candidate derives a point with a
+  // negative y-coordinate, we use the other candidate by negating the secret. This transformation of the secret simply flips the y-coordinate of the derived point while keeping the x-coordinate the same.
+  if (!(addressPointCandidate.y.toBigInt() <= (Fr.MODULUS - 1n) / 2n)) {
+    return new Fq(Fq.MODULUS - addressSecretCandidate.toBigInt());
+  }
+
+  return addressSecretCandidate;
+}
+
+export function derivePublicKeyFromSecretKey(secretKey: Fq) {
+  const curve = new Grumpkin();
+  return curve.mul(curve.generator(), secretKey);
+}
+
+/**
+ * Computes secret and public keys and public keys hash from a secret key.
+ * @param secretKey - The secret key to derive keys from.
+ * @returns The derived keys.
+ */
+export async function deriveKeys(secretKey: Fr) {
+  // First we derive master secret keys -  we use sha512 here because this derivation will never take place
+  // in a circuit
+  const masterNullifierSecretKey = deriveMasterNullifierSecretKey(secretKey);
+  const masterIncomingViewingSecretKey = deriveMasterIncomingViewingSecretKey(secretKey);
+  const masterOutgoingViewingSecretKey = deriveMasterOutgoingViewingSecretKey(secretKey);
+  const masterTaggingSecretKey = sha512ToGrumpkinScalar([secretKey, GeneratorIndex.TSK_M]);
+
+  // Then we derive master public keys
+  const masterNullifierPublicKey = await derivePublicKeyFromSecretKey(masterNullifierSecretKey);
+  const masterIncomingViewingPublicKey = await derivePublicKeyFromSecretKey(masterIncomingViewingSecretKey);
+  const masterOutgoingViewingPublicKey = await derivePublicKeyFromSecretKey(masterOutgoingViewingSecretKey);
+  const masterTaggingPublicKey = await derivePublicKeyFromSecretKey(masterTaggingSecretKey);
+
+  // We hash the public keys to get the public keys hash
+  const publicKeys = new PublicKeys(
+    masterNullifierPublicKey,
+    masterIncomingViewingPublicKey,
+    masterOutgoingViewingPublicKey,
+    masterTaggingPublicKey,
+  );
+
+  return {
+    masterNullifierSecretKey,
+    masterIncomingViewingSecretKey,
+    masterOutgoingViewingSecretKey,
+    masterTaggingSecretKey,
+    publicKeys,
+  };
+}
+
+// Returns shared tagging secret computed with Diffie-Hellman key exchange.
+export async function computeTaggingSecretPoint(
+  knownAddress: CompleteAddress,
+  ivsk: Fq,
+  externalAddress: AztecAddress,
+) {
+  const knownPreaddress = await computePreaddress(await knownAddress.publicKeys.hash(), knownAddress.partialAddress);
+  // TODO: #8970 - Computation of address point from x coordinate might fail
+  const externalAddressPoint = await externalAddress.toAddressPoint();
+  const curve = new Grumpkin();
+  // Given A (known complete address) -> B (external address) and h == preaddress
+  // Compute shared secret as S = (h_A + ivsk_A) * Addr_Point_B
+
+  // Beware! h_a + ivsk_a (also known as the address secret) can lead to an address point with a negative y-coordinate, since there's two possible candidates
+  // computeAddressSecret takes care of selecting the one that leads to a positive y-coordinate, which is the only valid address point
+  return curve.mul(externalAddressPoint, await computeAddressSecret(knownPreaddress, ivsk));
+}

package/src/keys/index.ts

@@ -0,0 +1,5 @@
+export * from './derivation.js';
+export * from './key_types.js';
+export * from './utils.js';
+export * from './public_key.js';
+export * from './public_keys.js';