@aztec/stdlib 5.0.0-nightly.20260701 → 5.0.0-nightly.20260702

package/src/contract/partial_address.ts

@@ -1,7 +1,13 @@
 import type { Fr } from '@aztec/foundation/curves/bn254';
 
 /**
- * A type which along with public key forms a preimage of a contract address. See the link below for more details
- * https://github.com/AztecProtocol/aztec-packages/blob/master/docs/docs/concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys
+ * The contract-side preimage of an Aztec address, i.e. the commitment to a specific contract instance.
+ *
+ * A partial address commits to a contract's code and initialization
+ * (`hash(contract_class_id, salted_initialization_hash)`) but not to its keys. Combined with an account's `PublicKeys`,
+ * it fully determines the address: `address = (hash(public_keys_hash, partial_address) * G + Ivpk_m).x`. Two accounts
+ * therefore share an address only if they share both their public keys and their partial address.
+ *
+ * See `computePartialAddress` for the derivation.
  */
 export type PartialAddress = Fr;

package/src/keys/derivation.ts

@@ -96,22 +96,51 @@ export function derivePublicKeyFromSecretKey(secretKey: Fq): Promise<PublicKey>
   return Grumpkin.mul(Grumpkin.generator, secretKey);
 }
 
+/**
+ * The six master secret keys that fully define an account's privacy keys.
+ */
+export type MasterSecretKeys = {
+  masterNullifierHidingKey: GrumpkinScalar;
+  masterIncomingViewingSecretKey: GrumpkinScalar;
+  masterOutgoingViewingSecretKey: GrumpkinScalar;
+  masterTaggingSecretKey: GrumpkinScalar;
+  masterMessageSigningSecretKey: GrumpkinScalar;
+  masterFallbackSecretKey: GrumpkinScalar;
+};
+
 /**
  * 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) {
+export function deriveKeys(secretKey: Fr) {
   // First we derive master secret/hiding keys -  we use sha512 here because this derivation will never take place
   // in a circuit
-  const masterNullifierHidingKey = deriveMasterNullifierHidingKey(secretKey);
-  const masterIncomingViewingSecretKey = deriveMasterIncomingViewingSecretKey(secretKey);
-  const masterOutgoingViewingSecretKey = deriveMasterOutgoingViewingSecretKey(secretKey);
-  const masterTaggingSecretKey = sha512ToGrumpkinScalar([secretKey, DomainSeparator.TSK_M]);
-  const masterMessageSigningSecretKey = deriveMasterMessageSigningSecretKey(secretKey);
-  const masterFallbackSecretKey = deriveMasterFallbackSecretKey(secretKey);
-
-  // Then we derive master public keys
+  return deriveKeysFromMasterSecretKeys({
+    masterNullifierHidingKey: deriveMasterNullifierHidingKey(secretKey),
+    masterIncomingViewingSecretKey: deriveMasterIncomingViewingSecretKey(secretKey),
+    masterOutgoingViewingSecretKey: deriveMasterOutgoingViewingSecretKey(secretKey),
+    masterTaggingSecretKey: sha512ToGrumpkinScalar([secretKey, DomainSeparator.TSK_M]),
+    masterMessageSigningSecretKey: deriveMasterMessageSigningSecretKey(secretKey),
+    masterFallbackSecretKey: deriveMasterFallbackSecretKey(secretKey),
+  });
+}
+
+/**
+ * Derives the master public keys and the {@link PublicKeys} struct from a set of master secret keys.
+ * @param secretKeys - The master secret keys to derive public keys from.
+ * @returns The provided secret keys alongside the derived public keys.
+ */
+export async function deriveKeysFromMasterSecretKeys(secretKeys: MasterSecretKeys) {
+  const {
+    masterNullifierHidingKey,
+    masterIncomingViewingSecretKey,
+    masterOutgoingViewingSecretKey,
+    masterTaggingSecretKey,
+    masterMessageSigningSecretKey,
+    masterFallbackSecretKey,
+  } = secretKeys;
+
   const masterNullifierPublicKey = await derivePublicKeyFromSecretKey(masterNullifierHidingKey);
   const masterIncomingViewingPublicKey = await derivePublicKeyFromSecretKey(masterIncomingViewingSecretKey);
   const masterOutgoingViewingPublicKey = await derivePublicKeyFromSecretKey(masterOutgoingViewingSecretKey);

package/src/logs/app_tagging_secret.ts

@@ -9,6 +9,7 @@ import { AztecAddress } from '../aztec-address/index.js';
 import type { CompleteAddress } from '../contract/complete_address.js';
 import { computeAddressSecret, computePreaddress } from '../keys/derivation.js';
 import { AppTaggingSecretKind } from './app_tagging_secret_kind.js';
+import { appSiloEcdhSharedSecretPoint } from './shared_secret_derivation.js';
 
 const AppTaggingSecretKindSchema = z.union([
   z.literal(AppTaggingSecretKind.UNCONSTRAINED),
@@ -32,32 +33,35 @@ export class AppTaggingSecret {
   /**
    * Derives an app-siloed, recipient-directional tagging secret from a shared tagging secret point.
    *
+   * App-silos the point via {@link appSiloEcdhSharedSecretPoint}, then directs the result to `recipient`:
+   * `h([s_app, recipient])`. The directional step stops a symmetric shared secret (ECDH against an address, or an
+   * arbitrary registered point) from colliding bidirectionally, so two parties never share a tag sequence.
+   *
    * The point is obtained either via {@link computeSharedTaggingSecret} (an ECDH key exchange against a sender) or
-   * registered directly as a pre-shared secret. Each secret point yields a distinct tagging secret per (app, recipient)
-   * pair.
+   * registered directly as a pre-shared secret.
    *
    * @param taggingSecretPoint - The shared tagging secret point (ECDH output, or a directly registered pre-shared secret)
    * @param app - Contract address to silo the secret to
    * @param recipient - Recipient of the log. Defines the "direction of the secret".
    * @returns The secret that can be used along with an index to compute a tag to be included in a log.
    */
-  static async compute(
+  static async computeDirectional(
     taggingSecretPoint: Point,
     app: AztecAddress,
     recipient: AztecAddress,
   ): Promise<AppTaggingSecret> {
-    const appTaggingSecret = await poseidon2Hash([taggingSecretPoint.x, taggingSecretPoint.y, app]);
-    const directionalAppTaggingSecret = await poseidon2Hash([appTaggingSecret, recipient]);
+    const appSiloedSecret = await appSiloEcdhSharedSecretPoint(taggingSecretPoint, app);
+    const directionalAppTaggingSecret = await poseidon2Hash([appSiloedSecret, recipient]);
 
     return new AppTaggingSecret(directionalAppTaggingSecret, app);
   }
 
   /**
-   * Derives the unconstrained tagging secret for `(externalAddress, recipient, app)` by performing the ECDH key
-   * exchange against `externalAddress` and then siloing and directing the result. Returns undefined if
-   * `externalAddress` is not a valid address.
+   * Derives the tagging secret for `(externalAddress, recipient, app)` by performing an ECDH key exchange against
+   * `externalAddress` to obtain the shared point, then siloing and directing it via {@link computeDirectional}.
+   * Returns undefined if `externalAddress` is not a valid address.
    */
-  static async computeUnconstrained(
+  static async computeViaEcdh(
     localAddress: CompleteAddress,
     localIvsk: Fq,
     externalAddress: AztecAddress,
@@ -69,7 +73,7 @@ export class AppTaggingSecret {
       return undefined;
     }
 
-    return AppTaggingSecret.compute(taggingSecretPoint, app, recipient);
+    return AppTaggingSecret.computeDirectional(taggingSecretPoint, app, recipient);
   }
 
   toString(): string {

package/src/logs/shared_secret_derivation.ts

@@ -2,16 +2,14 @@ import { DomainSeparator } from '@aztec/constants';
 import { Grumpkin } from '@aztec/foundation/crypto/grumpkin';
 import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 import type { Fr } from '@aztec/foundation/curves/bn254';
-import type { GrumpkinScalar } from '@aztec/foundation/curves/grumpkin';
+import type { GrumpkinScalar, Point } from '@aztec/foundation/curves/grumpkin';
 
 import type { AztecAddress } from '../aztec-address/index.js';
 import type { PublicKey } from '../keys/public_key.js';
 
 /**
- * Derives an app-siloed ECDH shared secret.
- *
- * Computes the raw ECDH shared secret `S = secretKey * publicKey`, then app-silos it:
- * `s_app = h(DOM_SEP__APP_SILOED_ECDH_SHARED_SECRET, S.x, S.y, contractAddress)`
+ * Derives an app-siloed ECDH shared secret from keys: ECDHs `S = secretKey * publicKey`, then app-silos it via
+ * {@link appSiloEcdhSharedSecretPoint}.
  *
  * @param secretKey - The secret key used to derive shared secret.
  * @param publicKey - The public key used to derive shared secret.
@@ -19,7 +17,7 @@ import type { PublicKey } from '../keys/public_key.js';
  * @returns The app-siloed shared secret as a Field.
  * @throws If the publicKey is zero.
  */
-export async function deriveAppSiloedSharedSecret(
+export async function appSiloEcdhSharedSecret(
   secretKey: GrumpkinScalar,
   publicKey: PublicKey,
   contractAddress: AztecAddress,
@@ -30,8 +28,17 @@ export async function deriveAppSiloedSharedSecret(
     );
   }
   const rawSharedSecret = await Grumpkin.mul(publicKey, secretKey);
-  return poseidon2HashWithSeparator(
-    [rawSharedSecret.x, rawSharedSecret.y, contractAddress],
-    DomainSeparator.APP_SILOED_ECDH_SHARED_SECRET,
-  );
+  return appSiloEcdhSharedSecretPoint(rawSharedSecret, contractAddress);
+}
+
+/**
+ * App-silos a shared secret point: `s_app = h(DOM_SEP__APP_SILOED_ECDH_SHARED_SECRET, S.x, S.y, app)`.
+ *
+ * Mirrors `compute_app_siloed_shared_secret` in aztec-nr.
+ *
+ * @param point - The raw shared secret point `S`.
+ * @param app - The contract address to silo to.
+ */
+export function appSiloEcdhSharedSecretPoint(point: Point, app: AztecAddress): Promise<Fr> {
+  return poseidon2HashWithSeparator([point.x, point.y, app], DomainSeparator.APP_SILOED_ECDH_SHARED_SECRET);
 }