@aztec/stdlib 0.0.1-commit.f504929 → 0.0.1-commit.f5a9928

package/dest/logs/app_tagging_secret.js

@@ -0,0 +1,116 @@
+import { Grumpkin } from '@aztec/foundation/crypto/grumpkin';
+import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { z } from 'zod';
+import { AztecAddress } from '../aztec-address/index.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),
+    z.literal(AppTaggingSecretKind.CONSTRAINED)
+]);
+/**
+ * Application tagging secret used for log tagging.
+ *
+ * It bundles a tagging secret with the app contract address. Unconstrained secrets are derived by the simulator from
+ * `(sender, recipient, app)` via ECDH. Constrained secrets are supplied to the simulator by the caller as an
+ * app-siloed shared secret retrieved from a handshake registry.
+ */ export class AppTaggingSecret {
+    secret;
+    app;
+    kind;
+    constructor(secret, app, kind = AppTaggingSecretKind.UNCONSTRAINED){
+        this.secret = secret;
+        this.app = app;
+        this.kind = kind;
+    }
+    /**
+   * 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.
+   *
+   * @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 computeDirectional(taggingSecretPoint, app, recipient) {
+        const appSiloedSecret = await appSiloEcdhSharedSecretPoint(taggingSecretPoint, app);
+        const directionalAppTaggingSecret = await poseidon2Hash([
+            appSiloedSecret,
+            recipient
+        ]);
+        return new AppTaggingSecret(directionalAppTaggingSecret, app);
+    }
+    /**
+   * Derives the bare app-siloed tagging secret from a shared secret point via {@link appSiloEcdhSharedSecretPoint},
+   * under the given delivery-mode kind.
+   */ static async computeAppSiloed(taggingSecretPoint, app, kind) {
+        return new AppTaggingSecret(await appSiloEcdhSharedSecretPoint(taggingSecretPoint, app), app, kind);
+    }
+    /**
+   * 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 computeViaEcdh(localAddress, localIvsk, externalAddress, app, recipient) {
+        const taggingSecretPoint = await computeSharedTaggingSecret(localAddress, localIvsk, externalAddress);
+        if (!taggingSecretPoint) {
+            return undefined;
+        }
+        return AppTaggingSecret.computeDirectional(taggingSecretPoint, app, recipient);
+    }
+    toString() {
+        return `${this.kind}:${this.secret.toString()}:${this.app.toString()}`;
+    }
+    static fromString(str) {
+        const parts = str.split(':');
+        if (parts.length !== 3) {
+            throw new Error(`Invalid AppTaggingSecret string: ${str}`);
+        }
+        const [kindStr, secretStr, appStr] = parts;
+        return new AppTaggingSecret(Fr.fromString(secretStr), AztecAddress.fromStringUnsafe(appStr), appTaggingSecretKindFromString(kindStr));
+    }
+}
+/**
+ * Parses a stored `AppTaggingSecret` string key.
+ */ export function appTaggingSecretFromString(str) {
+    return AppTaggingSecret.fromString(str);
+}
+export const AppTaggingSecretSchema = z.object({
+    kind: AppTaggingSecretKindSchema.default(AppTaggingSecretKind.UNCONSTRAINED),
+    secret: Fr.schema,
+    app: AztecAddress.schema
+}).transform(({ kind, secret, app })=>new AppTaggingSecret(secret, app, kind));
+function appTaggingSecretKindFromString(kind) {
+    switch(kind){
+        case AppTaggingSecretKind.CONSTRAINED:
+            return AppTaggingSecretKind.CONSTRAINED;
+        case AppTaggingSecretKind.UNCONSTRAINED:
+            return AppTaggingSecretKind.UNCONSTRAINED;
+        default:
+            throw new Error(`Invalid AppTaggingSecret kind: ${kind}`);
+    }
+}
+/**
+ * Computes the shared tagging secret point between a local address (i.e. one for which the privacy keys are known) and
+ * an external one via a Diffie-Hellman key exchange.
+ *
+ * Returns undefined if `externalAddress` is an invalid address.
+ */ export async function computeSharedTaggingSecret(localAddress, localIvsk, externalAddress) {
+    // An invalid address has no corresponding address point
+    if (!await externalAddress.isValid()) {
+        return undefined;
+    }
+    const externalAddressPoint = await externalAddress.toAddressPoint();
+    const localPreaddress = await computePreaddress(await localAddress.publicKeys.hash(), localAddress.partialAddress);
+    const localAddressSecret = await computeAddressSecret(localPreaddress, localIvsk);
+    // For a given local address A and external address B, the shared tagging secret S is (h_A + ivsk_A) * Addr_Point_B
+    // (conceptually, in reality we don't use h_A + ivsk_A directly but rather the actual address secret, which is the
+    // same but with an optional sign adjustment to prevent A's address point from having a negative y-coordinate).
+    return Grumpkin.mul(externalAddressPoint, localAddressSecret);
+}

package/dest/logs/app_tagging_secret_kind.d.ts

@@ -0,0 +1,7 @@
+export declare const AppTaggingSecretKind: {
+    readonly UNCONSTRAINED: "unconstrained";
+    readonly CONSTRAINED: "constrained";
+};
+export type AppTaggingSecretKind = (typeof AppTaggingSecretKind)[keyof typeof AppTaggingSecretKind];
+export declare function appTaggingSecretKindFromDeliveryMode(deliveryMode: number): AppTaggingSecretKind;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBwX3RhZ2dpbmdfc2VjcmV0X2tpbmQuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9sb2dzL2FwcF90YWdnaW5nX3NlY3JldF9raW5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGVBQU8sTUFBTSxvQkFBb0I7OztDQUd2QixDQUFDO0FBRVgsTUFBTSxNQUFNLG9CQUFvQixHQUFHLENBQUMsT0FBTyxvQkFBb0IsQ0FBQyxDQUFDLE1BQU0sT0FBTyxvQkFBb0IsQ0FBQyxDQUFDO0FBTXBHLHdCQUFnQixvQ0FBb0MsQ0FBQyxZQUFZLEVBQUUsTUFBTSxHQUFHLG9CQUFvQixDQVMvRiJ9

package/dest/logs/app_tagging_secret_kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app_tagging_secret_kind.d.ts","sourceRoot":"","sources":["../../src/logs/app_tagging_secret_kind.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB;;;CAGvB,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAMpG,wBAAgB,oCAAoC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAS/F"}

package/dest/logs/app_tagging_secret_kind.js

@@ -0,0 +1,17 @@
+export const AppTaggingSecretKind = {
+    UNCONSTRAINED: 'unconstrained',
+    CONSTRAINED: 'constrained'
+};
+// Keep in sync with aztec::messages::delivery::OnchainDeliveryMode.
+const ONCHAIN_UNCONSTRAINED_DELIVERY_MODE = 2;
+const ONCHAIN_CONSTRAINED_DELIVERY_MODE = 3;
+export function appTaggingSecretKindFromDeliveryMode(deliveryMode) {
+    switch(deliveryMode){
+        case ONCHAIN_UNCONSTRAINED_DELIVERY_MODE:
+            return AppTaggingSecretKind.UNCONSTRAINED;
+        case ONCHAIN_CONSTRAINED_DELIVERY_MODE:
+            return AppTaggingSecretKind.CONSTRAINED;
+        default:
+            throw new Error(`Unrecognized delivery mode for tagging: ${deliveryMode}`);
+    }
+}

package/dest/logs/contract_class_log.d.ts

@@ -1,5 +1,5 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader, FieldReader } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 import { inspect } from 'util';
 import { z } from 'zod';
@@ -7,15 +7,11 @@ import { AztecAddress } from '../aztec-address/index.js';
 export declare class ContractClassLogFields {
     fields: Fr[];
     constructor(fields: Fr[]);
-    static get schema(): z.ZodEffects<z.ZodObject<{
-        fields: z.ZodEffects<z.ZodArray<z.ZodType<Fr, any, string>, "many">, Fr[], string[]>;
-    }, "strip", z.ZodTypeAny, {
+    static get schema(): z.ZodPipe<z.ZodObject<{
+        fields: z.ZodArray<z.ZodType<Fr, string, z.core.$ZodTypeInternals<Fr, string>>>;
+    }, z.core.$strip>, z.ZodTransform<ContractClassLogFields, {
         fields: Fr[];
-    }, {
-        fields: string[];
-    }>, ContractClassLogFields, {
-        fields: string[];
-    }>;
+    }>>;
     /**
      * Creates a ContractClassLogFields from a plain object without Zod validation.
      * This method is optimized for performance and skips validation, making it suitable
@@ -26,7 +22,8 @@ export declare class ContractClassLogFields {
     static fromPlainObject(obj: any): ContractClassLogFields;
     toFields(): Fr[];
     static fromFields(fields: Fr[] | FieldReader): ContractClassLogFields;
-    toBuffer(): Buffer<ArrayBufferLike>;
+    toBuffer(): Buffer;
+    toBuffer(sink: BufferSink): void;
     static fromBuffer(buffer: Buffer | BufferReader): ContractClassLogFields;
     equals(other: ContractClassLogFields): boolean;
     getEmittedFields(emittedLength: number): Fr[];
@@ -46,45 +43,29 @@ export declare class ContractClassLog {
     static from(fields: FieldsOf<ContractClassLog>): ContractClassLog;
     toFields(): Fr[];
     equals(other: ContractClassLog): boolean;
-    static fromFields(fields: Fr[] | FieldReader): ContractClassLog;
     getEmittedFields(): Fr[];
     toBlobFields(): Fr[];
     static fromBlobFields(emittedLength: number, fields: Fr[] | FieldReader): ContractClassLog;
     isEmpty(): boolean;
     static empty(): ContractClassLog;
     toBuffer(): Buffer;
+    toBuffer(sink: BufferSink): void;
     static fromBuffer(buffer: Buffer | BufferReader): ContractClassLog;
     static random(): Promise<ContractClassLog>;
     hash(): Promise<Fr>;
-    static get schema(): z.ZodEffects<z.ZodObject<{
+    static get schema(): z.ZodPipe<z.ZodObject<{
         contractAddress: import("@aztec/foundation/schemas").ZodFor<AztecAddress>;
-        fields: z.ZodEffects<z.ZodObject<{
-            fields: z.ZodEffects<z.ZodArray<z.ZodType<Fr, any, string>, "many">, Fr[], string[]>;
-        }, "strip", z.ZodTypeAny, {
+        fields: z.ZodPipe<z.ZodObject<{
+            fields: z.ZodArray<z.ZodType<Fr, string, z.core.$ZodTypeInternals<Fr, string>>>;
+        }, z.core.$strip>, z.ZodTransform<ContractClassLogFields, {
             fields: Fr[];
-        }, {
-            fields: string[];
-        }>, ContractClassLogFields, {
-            fields: string[];
-        }>;
+        }>>;
         emittedLength: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
+    }, z.core.$strip>, z.ZodTransform<ContractClassLog, {
         contractAddress: AztecAddress;
         fields: ContractClassLogFields;
         emittedLength: number;
-    }, {
-        contractAddress?: any;
-        fields: {
-            fields: string[];
-        };
-        emittedLength: number;
-    }>, ContractClassLog, {
-        contractAddress?: any;
-        fields: {
-            fields: string[];
-        };
-        emittedLength: number;
-    }>;
+    }>>;
     /**
      * Creates a ContractClassLog from a plain object without Zod validation.
      * This method is optimized for performance and skips validation, making it suitable
@@ -95,4 +76,4 @@ export declare class ContractClassLog {
     static fromPlainObject(obj: any): ContractClassLog;
     [inspect.custom](): string;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udHJhY3RfY2xhc3NfbG9nLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbG9ncy9jb250cmFjdF9jbGFzc19sb2cudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBRUEsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBRXBELE9BQU8sRUFBRSxZQUFZLEVBQUUsV0FBVyxFQUF3QyxNQUFNLDZCQUE2QixDQUFDO0FBQzlHLE9BQU8sS0FBSyxFQUFFLFFBQVEsRUFBRSxNQUFNLHlCQUF5QixDQUFDO0FBRXhELE9BQU8sRUFBRSxPQUFPLEVBQUUsTUFBTSxNQUFNLENBQUM7QUFDL0IsT0FBTyxFQUFFLENBQUMsRUFBRSxNQUFNLEtBQUssQ0FBQztBQUV4QixPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sMkJBQTJCLENBQUM7QUFFekQscUJBQWEsc0JBQXNCO0lBR2QsTUFBTSxFQUFFLEVBQUUsRUFBRTtJQUEvQixZQUFtQixNQUFNLEVBQUUsRUFBRSxFQUFFLEVBTTlCO0lBRUQsTUFBTSxLQUFLLE1BQU07Ozs7Ozs7O09BTWhCO0lBRUQ7Ozs7OztPQU1HO0lBQ0gsTUFBTSxDQUFDLGVBQWUsQ0FBQyxHQUFHLEVBQUUsR0FBRyxHQUFHLHNCQUFzQixDQUt2RDtJQUVELFFBQVEsSUFBSSxFQUFFLEVBQUUsQ0FFZjtJQUVELE1BQU0sQ0FBQyxVQUFVLENBQUMsTUFBTSxFQUFFLEVBQUUsRUFBRSxHQUFHLFdBQVcsMEJBTzNDO0lBRUQsUUFBUSw0QkFFUDtJQUVELE1BQU0sQ0FBQyxVQUFVLENBQUMsTUFBTSxFQUFFLE1BQU0sR0FBRyxZQUFZLDBCQU85QztJQUVELE1BQU0sQ0FBQyxLQUFLLEVBQUUsc0JBQXNCLFdBRW5DO0lBRUQsZ0JBQWdCLENBQUMsYUFBYSxFQUFFLE1BQU0sUUFFckM7SUFFRCxNQUFNLENBQUMsaUJBQWlCLENBQUMsYUFBYSxFQUFFLEVBQUUsRUFBRSwwQkFJM0M7SUFFRCxPQUFPLFlBRU47SUFFRCxNQUFNLENBQUMsS0FBSywyQkFFWDtJQUVELE1BQU0sQ0FBQyxNQUFNLENBQUMsYUFBYSxTQUFvQywwQkFNOUQ7SUFFSyxJQUFJLGdCQUVUO0lBRUQsS0FBSywyQkFFSjtDQUNGO0FBRUQscUJBQWEsZ0JBQWdCO0lBSWxCLGVBQWUsRUFBRSxZQUFZO0lBQzdCLE1BQU0sRUFBRSxzQkFBc0I7SUFDOUIsYUFBYSxFQUFFLE1BQU07SUFMOUIsTUFBTSxDQUFDLGFBQWEsU0FBZ0Q7SUFFcEUsWUFDUyxlQUFlLEVBQUUsWUFBWSxFQUM3QixNQUFNLEVBQUUsc0JBQXNCLEVBQzlCLGFBQWEsRUFBRSxNQUFNLEVBQzFCO0lBRUosTUFBTSxDQUFDLElBQUksQ0FBQyxNQUFNLEVBQUUsUUFBUSxDQUFDLGdCQUFnQixDQUFDLG9CQUU3QztJQUVELFFBQVEsSUFBSSxFQUFFLEVBQUUsQ0FFZjtJQUVELE1BQU0sQ0FBQyxLQUFLLEVBQUUsZ0JBQWdCLFdBTTdCO0lBRUQsTUFBTSxDQUFDLFVBQVUsQ0FBQyxNQUFNLEVBQUUsRUFBRSxFQUFFLEdBQUcsV0FBVyxvQkFPM0M7SUFFRCxnQkFBZ0IsU0FFZjtJQUVELFlBQVksSUFBSSxFQUFFLEVBQUUsQ0FFbkI7SUFFRCxNQUFNLENBQUMsY0FBYyxDQUFDLGFBQWEsRUFBRSxNQUFNLEVBQUUsTUFBTSxFQUFFLEVBQUUsRUFBRSxHQUFHLFdBQVcsb0JBU3RFO0lBRUQsT0FBTyxZQUVOO0lBRUQsTUFBTSxDQUFDLEtBQUsscUJBRVg7SUFFRCxRQUFRLElBQUksTUFBTSxDQUVqQjtJQUVELE1BQU0sQ0FBQyxVQUFVLENBQUMsTUFBTSxFQUFFLE1BQU0sR0FBRyxZQUFZLG9CQU05QztJQUVELE9BQWEsTUFBTSw4QkFRbEI7SUFFSyxJQUFJLGdCQUVUO0lBRUQsTUFBTSxLQUFLLE1BQU07Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7T0FRaEI7SUFFRDs7Ozs7O09BTUc7SUFDSCxNQUFNLENBQUMsZUFBZSxDQUFDLEdBQUcsRUFBRSxHQUFHLEdBQUcsZ0JBQWdCLENBU2pEO0lBRUQsQ0FBQyxPQUFPLENBQUMsTUFBTSxDQUFDLElBQUksTUFBTSxDQU16QjtDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29udHJhY3RfY2xhc3NfbG9nLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbG9ncy9jb250cmFjdF9jbGFzc19sb2cudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBRUEsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBRXBELE9BQU8sRUFBRSxZQUFZLEVBQUUsVUFBVSxFQUFFLFdBQVcsRUFBc0MsTUFBTSw2QkFBNkIsQ0FBQztBQUN4SCxPQUFPLEtBQUssRUFBRSxRQUFRLEVBQUUsTUFBTSx5QkFBeUIsQ0FBQztBQUV4RCxPQUFPLEVBQUUsT0FBTyxFQUFFLE1BQU0sTUFBTSxDQUFDO0FBQy9CLE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFeEIsT0FBTyxFQUFFLFlBQVksRUFBRSxNQUFNLDJCQUEyQixDQUFDO0FBRXpELHFCQUFhLHNCQUFzQjtJQUdkLE1BQU0sRUFBRSxFQUFFLEVBQUU7SUFBL0IsWUFBbUIsTUFBTSxFQUFFLEVBQUUsRUFBRSxFQU05QjtJQUVELE1BQU0sS0FBSyxNQUFNOzs7O1FBTWhCO0lBRUQ7Ozs7OztPQU1HO0lBQ0gsTUFBTSxDQUFDLGVBQWUsQ0FBQyxHQUFHLEVBQUUsR0FBRyxHQUFHLHNCQUFzQixDQUt2RDtJQUVELFFBQVEsSUFBSSxFQUFFLEVBQUUsQ0FFZjtJQUVELE1BQU0sQ0FBQyxVQUFVLENBQUMsTUFBTSxFQUFFLEVBQUUsRUFBRSxHQUFHLFdBQVcsMEJBTzNDO0lBRUQsUUFBUSxJQUFJLE1BQU0sQ0FBQztJQUNuQixRQUFRLENBQUMsSUFBSSxFQUFFLFVBQVUsR0FBRyxJQUFJLENBQUM7SUFRakMsTUFBTSxDQUFDLFVBQVUsQ0FBQyxNQUFNLEVBQUUsTUFBTSxHQUFHLFlBQVksMEJBTzlDO0lBRUQsTUFBTSxDQUFDLEtBQUssRUFBRSxzQkFBc0IsV0FFbkM7SUFFRCxnQkFBZ0IsQ0FBQyxhQUFhLEVBQUUsTUFBTSxRQUVyQztJQUVELE1BQU0sQ0FBQyxpQkFBaUIsQ0FBQyxhQUFhLEVBQUUsRUFBRSxFQUFFLDBCQUkzQztJQUVELE9BQU8sWUFFTjtJQUVELE1BQU0sQ0FBQyxLQUFLLDJCQUVYO0lBRUQsTUFBTSxDQUFDLE1BQU0sQ0FBQyxhQUFhLFNBQW9DLDBCQU05RDtJQUVLLElBQUksZ0JBRVQ7SUFFRCxLQUFLLDJCQUVKO0NBQ0Y7QUFFRCxxQkFBYSxnQkFBZ0I7SUFJbEIsZUFBZSxFQUFFLFlBQVk7SUFDN0IsTUFBTSxFQUFFLHNCQUFzQjtJQUM5QixhQUFhLEVBQUUsTUFBTTtJQUw5QixNQUFNLENBQUMsYUFBYSxTQUFnRDtJQUVwRSxZQUNTLGVBQWUsRUFBRSxZQUFZLEVBQzdCLE1BQU0sRUFBRSxzQkFBc0IsRUFDOUIsYUFBYSxFQUFFLE1BQU0sRUFDMUI7SUFFSixNQUFNLENBQUMsSUFBSSxDQUFDLE1BQU0sRUFBRSxRQUFRLENBQUMsZ0JBQWdCLENBQUMsb0JBRTdDO0lBRUQsUUFBUSxJQUFJLEVBQUUsRUFBRSxDQUVmO0lBRUQsTUFBTSxDQUFDLEtBQUssRUFBRSxnQkFBZ0IsV0FNN0I7SUFFRCxnQkFBZ0IsU0FFZjtJQUVELFlBQVksSUFBSSxFQUFFLEVBQUUsQ0FFbkI7SUFFRCxNQUFNLENBQUMsY0FBYyxDQUFDLGFBQWEsRUFBRSxNQUFNLEVBQUUsTUFBTSxFQUFFLEVBQUUsRUFBRSxHQUFHLFdBQVcsb0JBU3RFO0lBRUQsT0FBTyxZQUVOO0lBRUQsTUFBTSxDQUFDLEtBQUsscUJBRVg7SUFFRCxRQUFRLElBQUksTUFBTSxDQUFDO0lBQ25CLFFBQVEsQ0FBQyxJQUFJLEVBQUUsVUFBVSxHQUFHLElBQUksQ0FBQztJQVFqQyxNQUFNLENBQUMsVUFBVSxDQUFDLE1BQU0sRUFBRSxNQUFNLEdBQUcsWUFBWSxvQkFNOUM7SUFFRCxPQUFhLE1BQU0sOEJBUWxCO0lBRUssSUFBSSxnQkFFVDtJQUVELE1BQU0sS0FBSyxNQUFNOzs7Ozs7Ozs7Ozs7UUFRaEI7SUFFRDs7Ozs7O09BTUc7SUFDSCxNQUFNLENBQUMsZUFBZSxDQUFDLEdBQUcsRUFBRSxHQUFHLEdBQUcsZ0JBQWdCLENBU2pEO0lBRUQsQ0FBQyxPQUFPLENBQUMsTUFBTSxDQUFDLElBQUksTUFBTSxDQU16QjtDQUNGIn0=

package/dest/logs/contract_class_log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract_class_log.d.ts","sourceRoot":"","sources":["../../src/logs/contract_class_log.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAwC,MAAM,6BAA6B,CAAC;AAC9G,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,qBAAa,sBAAsB;IAGd,MAAM,EAAE,EAAE,EAAE;IAA/B,YAAmB,MAAM,EAAE,EAAE,EAAE,EAM9B;IAED,MAAM,KAAK,MAAM;;;;;;;;OAMhB;IAED;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,sBAAsB,CAKvD;IAED,QAAQ,IAAI,EAAE,EAAE,CAEf;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,WAAW,0BAO3C;IAED,QAAQ,4BAEP;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,0BAO9C;IAED,MAAM,CAAC,KAAK,EAAE,sBAAsB,WAEnC;IAED,gBAAgB,CAAC,aAAa,EAAE,MAAM,QAErC;IAED,MAAM,CAAC,iBAAiB,CAAC,aAAa,EAAE,EAAE,EAAE,0BAI3C;IAED,OAAO,YAEN;IAED,MAAM,CAAC,KAAK,2BAEX;IAED,MAAM,CAAC,MAAM,CAAC,aAAa,SAAoC,0BAM9D;IAEK,IAAI,gBAET;IAED,KAAK,2BAEJ;CACF;AAED,qBAAa,gBAAgB;IAIlB,eAAe,EAAE,YAAY;IAC7B,MAAM,EAAE,sBAAsB;IAC9B,aAAa,EAAE,MAAM;IAL9B,MAAM,CAAC,aAAa,SAAgD;IAEpE,YACS,eAAe,EAAE,YAAY,EAC7B,MAAM,EAAE,sBAAsB,EAC9B,aAAa,EAAE,MAAM,EAC1B;IAEJ,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,oBAE7C;IAED,QAAQ,IAAI,EAAE,EAAE,CAEf;IAED,MAAM,CAAC,KAAK,EAAE,gBAAgB,WAM7B;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,WAAW,oBAO3C;IAED,gBAAgB,SAEf;IAED,YAAY,IAAI,EAAE,EAAE,CAEnB;IAED,MAAM,CAAC,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,WAAW,oBAStE;IAED,OAAO,YAEN;IAED,MAAM,CAAC,KAAK,qBAEX;IAED,QAAQ,IAAI,MAAM,CAEjB;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,oBAM9C;IAED,OAAa,MAAM,8BAQlB;IAEK,IAAI,gBAET;IAED,MAAM,KAAK,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAQhB;IAED;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,gBAAgB,CASjD;IAED,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAMzB;CACF"}
+{"version":3,"file":"contract_class_log.d.ts","sourceRoot":"","sources":["../../src/logs/contract_class_log.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAsC,MAAM,6BAA6B,CAAC;AACxH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,qBAAa,sBAAsB;IAGd,MAAM,EAAE,EAAE,EAAE;IAA/B,YAAmB,MAAM,EAAE,EAAE,EAAE,EAM9B;IAED,MAAM,KAAK,MAAM;;;;QAMhB;IAED;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,sBAAsB,CAKvD;IAED,QAAQ,IAAI,EAAE,EAAE,CAEf;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,WAAW,0BAO3C;IAED,QAAQ,IAAI,MAAM,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAQjC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,0BAO9C;IAED,MAAM,CAAC,KAAK,EAAE,sBAAsB,WAEnC;IAED,gBAAgB,CAAC,aAAa,EAAE,MAAM,QAErC;IAED,MAAM,CAAC,iBAAiB,CAAC,aAAa,EAAE,EAAE,EAAE,0BAI3C;IAED,OAAO,YAEN;IAED,MAAM,CAAC,KAAK,2BAEX;IAED,MAAM,CAAC,MAAM,CAAC,aAAa,SAAoC,0BAM9D;IAEK,IAAI,gBAET;IAED,KAAK,2BAEJ;CACF;AAED,qBAAa,gBAAgB;IAIlB,eAAe,EAAE,YAAY;IAC7B,MAAM,EAAE,sBAAsB;IAC9B,aAAa,EAAE,MAAM;IAL9B,MAAM,CAAC,aAAa,SAAgD;IAEpE,YACS,eAAe,EAAE,YAAY,EAC7B,MAAM,EAAE,sBAAsB,EAC9B,aAAa,EAAE,MAAM,EAC1B;IAEJ,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,oBAE7C;IAED,QAAQ,IAAI,EAAE,EAAE,CAEf;IAED,MAAM,CAAC,KAAK,EAAE,gBAAgB,WAM7B;IAED,gBAAgB,SAEf;IAED,YAAY,IAAI,EAAE,EAAE,CAEnB;IAED,MAAM,CAAC,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,WAAW,oBAStE;IAED,OAAO,YAEN;IAED,MAAM,CAAC,KAAK,qBAEX;IAED,QAAQ,IAAI,MAAM,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAQjC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,oBAM9C;IAED,OAAa,MAAM,8BAQlB;IAEK,IAAI,gBAET;IAED,MAAM,KAAK,MAAM;;;;;;;;;;;;QAQhB;IAED;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,gBAAgB,CASjD;IAED,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAMzB;CACF"}

package/dest/logs/contract_class_log.js

@@ -3,7 +3,7 @@ import { CONTRACT_CLASS_LOG_LENGTH, CONTRACT_CLASS_LOG_SIZE_IN_FIELDS } from '@a
 import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
-import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields, serializeToSink } from '@aztec/foundation/serialize';
 import { inspect } from 'util';
 import { z } from 'zod';
 import { AztecAddress } from '../aztec-address/index.js';
@@ -45,8 +45,11 @@ export class ContractClassLogFields {
             length: CONTRACT_CLASS_LOG_SIZE_IN_FIELDS
         }, ()=>reader.readField()));
     }
-    toBuffer() {
-        return serializeToBuffer(this.fields);
+    toBuffer(sink) {
+        if (!sink) {
+            return BufferSink.serialize(this);
+        }
+        serializeToSink(sink, this.fields);
     }
     static fromBuffer(buffer) {
         const reader = BufferReader.asReader(buffer);
@@ -107,10 +110,6 @@ export class ContractClassLog {
     equals(other) {
         return this.contractAddress.equals(other.contractAddress) && this.fields.equals(other.fields) && this.emittedLength === other.emittedLength;
     }
-    static fromFields(fields) {
-        const reader = FieldReader.asReader(fields);
-        return new ContractClassLog(reader.readObject(AztecAddress), reader.readObject(ContractClassLogFields), reader.readU32());
-    }
     getEmittedFields() {
         return this.fields.getEmittedFields(this.emittedLength);
     }
@@ -131,12 +130,11 @@ export class ContractClassLog {
     static empty() {
         return new ContractClassLog(AztecAddress.ZERO, ContractClassLogFields.empty(), 0);
     }
-    toBuffer() {
-        return serializeToBuffer([
-            this.contractAddress,
-            this.fields,
-            this.emittedLength
-        ]);
+    toBuffer(sink) {
+        if (!sink) {
+            return BufferSink.serialize(this);
+        }
+        serializeToSink(sink, this.contractAddress, this.fields, this.emittedLength);
     }
     static fromBuffer(buffer) {
         const reader = BufferReader.asReader(buffer);

package/dest/logs/index.d.ts

@@ -1,18 +1,17 @@
-export * from './extended_directional_app_tagging_secret.js';
+export * from './app_tagging_secret_kind.js';
+export * from './app_tagging_secret.js';
 export * from './pre_tag.js';
+export * from './tagging_index_range.js';
 export * from './contract_class_log.js';
 export * from './public_log.js';
 export * from './private_log.js';
-export * from './pending_tagged_log.js';
-export * from './log_id.js';
-export * from './log_filter.js';
-export * from './extended_public_log.js';
-export * from './extended_contract_class_log.js';
+export * from './log_result.js';
+export * from './log_cursor.js';
+export * from './logs_query.js';
+export * from './query_all_logs_by_tags.js';
 export * from './shared_secret_derivation.js';
-export * from './tx_scoped_l2_log.js';
-export * from './message_context.js';
 export * from './debug_log.js';
 export * from './debug_log_store.js';
 export * from './tag.js';
 export * from './siloed_tag.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9sb2dzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsOENBQThDLENBQUM7QUFDN0QsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyx5QkFBeUIsQ0FBQztBQUN4QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyx5QkFBeUIsQ0FBQztBQUN4QyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxrQ0FBa0MsQ0FBQztBQUNqRCxjQUFjLCtCQUErQixDQUFDO0FBQzlDLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxpQkFBaUIsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9sb2dzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsOEJBQThCLENBQUM7QUFDN0MsY0FBYyx5QkFBeUIsQ0FBQztBQUN4QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYywrQkFBK0IsQ0FBQztBQUM5QyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxpQkFBaUIsQ0FBQyJ9

package/dest/logs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logs/index.ts"],"names":[],"mappings":"AAAA,cAAc,8CAA8C,CAAC;AAC7D,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logs/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC"}

package/dest/logs/index.js

@@ -1,16 +1,15 @@
-export * from './extended_directional_app_tagging_secret.js';
+export * from './app_tagging_secret_kind.js';
+export * from './app_tagging_secret.js';
 export * from './pre_tag.js';
+export * from './tagging_index_range.js';
 export * from './contract_class_log.js';
 export * from './public_log.js';
 export * from './private_log.js';
-export * from './pending_tagged_log.js';
-export * from './log_id.js';
-export * from './log_filter.js';
-export * from './extended_public_log.js';
-export * from './extended_contract_class_log.js';
+export * from './log_result.js';
+export * from './log_cursor.js';
+export * from './logs_query.js';
+export * from './query_all_logs_by_tags.js';
 export * from './shared_secret_derivation.js';
-export * from './tx_scoped_l2_log.js';
-export * from './message_context.js';
 export * from './debug_log.js';
 export * from './debug_log_store.js';
 export * from './tag.js';

package/dest/logs/log_cursor.d.ts

@@ -0,0 +1,51 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { BufferReader } from '@aztec/foundation/serialize';
+import { z } from 'zod';
+import type { LogResultBase } from './log_result.js';
+/**
+ * Cursor identifying a position in a tag's ordered log stream. Used as `afterLog` on `TagQuery` to resume
+ * pagination strictly after a previously-seen log.
+ *
+ * `(blockNumber, txIndexWithinBlock, logIndexWithinTx)` is sufficient to uniquely identify a position
+ * and matches the composite-key ordering of the archiver's log index, so the cursor maps directly to a
+ * key without a tx-hash lookup. All three fields are always present on {@link LogResult}, so a cursor is
+ * constructible from any returned log.
+ */
+export declare class LogCursor {
+    /** The block the cursor points to. */
+    readonly blockNumber: BlockNumber;
+    /** The tx index within the block the cursor points to. */
+    readonly txIndexWithinBlock: number;
+    /** The log index within the tx the cursor points to. */
+    readonly logIndexWithinTx: number;
+    constructor(
+    /** The block the cursor points to. */
+    blockNumber: BlockNumber, 
+    /** The tx index within the block the cursor points to. */
+    txIndexWithinBlock: number, 
+    /** The log index within the tx the cursor points to. */
+    logIndexWithinTx: number);
+    static get schema(): z.ZodPipe<z.ZodObject<{
+        blockNumber: z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodPipe<z.ZodBigInt, z.ZodTransform<number, bigint>>, z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>]>, z.ZodTransform<BlockNumber, number>>;
+        txIndexWithinBlock: z.ZodPipe<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber, z.ZodString]>, z.ZodCoercedNumber<string | number | bigint>>;
+        logIndexWithinTx: z.ZodPipe<z.ZodUnion<readonly [z.ZodBigInt, z.ZodNumber, z.ZodString]>, z.ZodCoercedNumber<string | number | bigint>>;
+    }, z.core.$strip>, z.ZodTransform<LogCursor, {
+        blockNumber: BlockNumber;
+        txIndexWithinBlock: number;
+        logIndexWithinTx: number;
+    }>>;
+    /** Builds a cursor that points at the given log. Pagination resumes strictly after this position. */
+    static fromLog(log: Pick<LogResultBase, 'blockNumber' | 'txIndexWithinBlock' | 'logIndexWithinTx'>): LogCursor;
+    static random(): LogCursor;
+    toBuffer(): Buffer;
+    static fromBuffer(buffer: Buffer | BufferReader): LogCursor;
+    equals(other: LogCursor): boolean;
+    toString(): string;
+    /**
+     * Parses a `<blockNumber>-<txIndexWithinBlock>-<logIndexWithinTx>` triple into a {@link LogCursor}.
+     * Throws on malformed input. Returns `undefined` for an empty / missing value so callers can use
+     * this directly as an optional CLI option parser.
+     */
+    static parseOptional(value: string): LogCursor | undefined;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibG9nX2N1cnNvci5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2xvZ3MvbG9nX2N1cnNvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsV0FBVyxFQUFxQixNQUFNLGlDQUFpQyxDQUFDO0FBQ2pGLE9BQU8sRUFBRSxZQUFZLEVBQWlCLE1BQU0sNkJBQTZCLENBQUM7QUFFMUUsT0FBTyxFQUFFLENBQUMsRUFBRSxNQUFNLEtBQUssQ0FBQztBQUd4QixPQUFPLEtBQUssRUFBRSxhQUFhLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUVyRDs7Ozs7Ozs7R0FRRztBQUNILHFCQUFhLFNBQVM7SUFFbEIsc0NBQXNDO2FBQ3RCLFdBQVcsRUFBRSxXQUFXO0lBQ3hDLDBEQUEwRDthQUMxQyxrQkFBa0IsRUFBRSxNQUFNO0lBQzFDLHdEQUF3RDthQUN4QyxnQkFBZ0IsRUFBRSxNQUFNO0lBTjFDO0lBQ0Usc0NBQXNDO0lBQ3RCLFdBQVcsRUFBRSxXQUFXO0lBQ3hDLDBEQUEwRDtJQUMxQyxrQkFBa0IsRUFBRSxNQUFNO0lBQzFDLHdEQUF3RDtJQUN4QyxnQkFBZ0IsRUFBRSxNQUFNLEVBQ3RDO0lBRUosTUFBTSxLQUFLLE1BQU07Ozs7Ozs7O1FBV2hCO0lBRUQscUdBQXFHO0lBQ3JHLE1BQU0sQ0FBQyxPQUFPLENBQUMsR0FBRyxFQUFFLElBQUksQ0FBQyxhQUFhLEVBQUUsYUFBYSxHQUFHLG9CQUFvQixHQUFHLGtCQUFrQixDQUFDLEdBQUcsU0FBUyxDQUU3RztJQUVELE1BQU0sQ0FBQyxNQUFNLElBQUksU0FBUyxDQU16QjtJQUVELFFBQVEsSUFBSSxNQUFNLENBTWpCO0lBRUQsTUFBTSxDQUFDLFVBQVUsQ0FBQyxNQUFNLEVBQUUsTUFBTSxHQUFHLFlBQVksR0FBRyxTQUFTLENBTTFEO0lBRUQsTUFBTSxDQUFDLEtBQUssRUFBRSxTQUFTLEdBQUcsT0FBTyxDQU1oQztJQUVELFFBQVEsSUFBSSxNQUFNLENBRWpCO0lBRUQ7Ozs7T0FJRztJQUNILE1BQU0sQ0FBQyxhQUFhLENBQUMsS0FBSyxFQUFFLE1BQU0sR0FBRyxTQUFTLEdBQUcsU0FBUyxDQXNCekQ7Q0FDRiJ9

package/dest/logs/log_cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log_cursor.d.ts","sourceRoot":"","sources":["../../src/logs/log_cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAqB,MAAM,iCAAiC,CAAC;AACjF,OAAO,EAAE,YAAY,EAAiB,MAAM,6BAA6B,CAAC;AAE1E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,qBAAa,SAAS;IAElB,sCAAsC;aACtB,WAAW,EAAE,WAAW;IACxC,0DAA0D;aAC1C,kBAAkB,EAAE,MAAM;IAC1C,wDAAwD;aACxC,gBAAgB,EAAE,MAAM;IAN1C;IACE,sCAAsC;IACtB,WAAW,EAAE,WAAW;IACxC,0DAA0D;IAC1C,kBAAkB,EAAE,MAAM;IAC1C,wDAAwD;IACxC,gBAAgB,EAAE,MAAM,EACtC;IAEJ,MAAM,KAAK,MAAM;;;;;;;;QAWhB;IAED,qGAAqG;IACrG,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,GAAG,oBAAoB,GAAG,kBAAkB,CAAC,GAAG,SAAS,CAE7G;IAED,MAAM,CAAC,MAAM,IAAI,SAAS,CAMzB;IAED,QAAQ,IAAI,MAAM,CAMjB;IAED,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAM1D;IAED,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAMhC;IAED,QAAQ,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAsBzD;CACF"}

package/dest/logs/log_cursor.js

@@ -0,0 +1,82 @@
+import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
+import { BufferReader, numToUInt32BE } from '@aztec/foundation/serialize';
+import { z } from 'zod';
+import { schemas } from '../schemas/schemas.js';
+/**
+ * Cursor identifying a position in a tag's ordered log stream. Used as `afterLog` on `TagQuery` to resume
+ * pagination strictly after a previously-seen log.
+ *
+ * `(blockNumber, txIndexWithinBlock, logIndexWithinTx)` is sufficient to uniquely identify a position
+ * and matches the composite-key ordering of the archiver's log index, so the cursor maps directly to a
+ * key without a tx-hash lookup. All three fields are always present on {@link LogResult}, so a cursor is
+ * constructible from any returned log.
+ */ export class LogCursor {
+    blockNumber;
+    txIndexWithinBlock;
+    logIndexWithinTx;
+    constructor(/** The block the cursor points to. */ blockNumber, /** The tx index within the block the cursor points to. */ txIndexWithinBlock, /** The log index within the tx the cursor points to. */ logIndexWithinTx){
+        this.blockNumber = blockNumber;
+        this.txIndexWithinBlock = txIndexWithinBlock;
+        this.logIndexWithinTx = logIndexWithinTx;
+    }
+    static get schema() {
+        return z.object({
+            blockNumber: BlockNumberSchema,
+            txIndexWithinBlock: schemas.Integer,
+            logIndexWithinTx: schemas.Integer
+        }).transform(({ blockNumber, txIndexWithinBlock, logIndexWithinTx })=>new LogCursor(blockNumber, txIndexWithinBlock, logIndexWithinTx));
+    }
+    /** Builds a cursor that points at the given log. Pagination resumes strictly after this position. */ static fromLog(log) {
+        return new LogCursor(log.blockNumber, log.txIndexWithinBlock, log.logIndexWithinTx);
+    }
+    static random() {
+        return new LogCursor(BlockNumber(Math.floor(Math.random() * 100000) + 1), Math.floor(Math.random() * 100), Math.floor(Math.random() * 100));
+    }
+    toBuffer() {
+        return Buffer.concat([
+            numToUInt32BE(this.blockNumber),
+            numToUInt32BE(this.txIndexWithinBlock),
+            numToUInt32BE(this.logIndexWithinTx)
+        ]);
+    }
+    static fromBuffer(buffer) {
+        const reader = BufferReader.asReader(buffer);
+        const blockNumber = BlockNumber(reader.readNumber());
+        const txIndexWithinBlock = reader.readNumber();
+        const logIndexWithinTx = reader.readNumber();
+        return new LogCursor(blockNumber, txIndexWithinBlock, logIndexWithinTx);
+    }
+    equals(other) {
+        return this.blockNumber === other.blockNumber && this.txIndexWithinBlock === other.txIndexWithinBlock && this.logIndexWithinTx === other.logIndexWithinTx;
+    }
+    toString() {
+        return `${this.blockNumber}-${this.txIndexWithinBlock}-${this.logIndexWithinTx}`;
+    }
+    /**
+   * Parses a `<blockNumber>-<txIndexWithinBlock>-<logIndexWithinTx>` triple into a {@link LogCursor}.
+   * Throws on malformed input. Returns `undefined` for an empty / missing value so callers can use
+   * this directly as an optional CLI option parser.
+   */ static parseOptional(value) {
+        if (!value) {
+            return undefined;
+        }
+        const parts = value.split('-');
+        if (parts.length !== 3) {
+            throw new Error(`Invalid log cursor "${value}". Expected <blockNumber>-<txIndexWithinBlock>-<logIndexWithinTx>.`);
+        }
+        const [blockNumberStr, txIndexStr, logIndexStr] = parts;
+        const blockNumber = Number(blockNumberStr);
+        const txIndexWithinBlock = Number(txIndexStr);
+        const logIndexWithinTx = Number(logIndexStr);
+        if (!Number.isInteger(blockNumber) || blockNumber < 1) {
+            throw new Error(`Invalid log cursor block number: ${blockNumberStr}`);
+        }
+        if (!Number.isInteger(txIndexWithinBlock) || txIndexWithinBlock < 0) {
+            throw new Error(`Invalid log cursor tx index: ${txIndexStr}`);
+        }
+        if (!Number.isInteger(logIndexWithinTx) || logIndexWithinTx < 0) {
+            throw new Error(`Invalid log cursor log index: ${logIndexStr}`);
+        }
+        return new LogCursor(BlockNumber(blockNumber), txIndexWithinBlock, logIndexWithinTx);
+    }
+}

package/dest/logs/log_result.d.ts

@@ -0,0 +1,54 @@
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import type { PickIfFlag, Prettify } from '@aztec/foundation/types';
+import { z } from 'zod';
+import { BlockHash } from '../block/block_hash.js';
+import { TxHash } from '../tx/tx_hash.js';
+import type { UInt64 } from '../types/shared.js';
+/** Options for narrowing the shape of a {@link LogResult}. */
+export type LogIncludeOptions = {
+    /** When set, the log carries `noteHashes` + all `nullifiers` from its tx effect. Off by default. */
+    includeEffects?: boolean;
+};
+export declare const LogIncludeOptionsSchema: z.ZodType<LogIncludeOptions>;
+/** Required metadata always present on a {@link LogResult}. */
+export type LogResultBase = {
+    /** The data contents of the log, with the tag as the first field. */
+    logData: Fr[];
+    /** The block this log was emitted in. */
+    blockNumber: BlockNumber;
+    /** The hash of the block this log was emitted in. */
+    blockHash: BlockHash;
+    /** The timestamp of the block this log was emitted in. */
+    blockTimestamp: UInt64;
+    /** The hash of the tx this log was emitted in. */
+    txHash: TxHash;
+    /** The 0-based index of this log's tx within its block. */
+    txIndexWithinBlock: number;
+    /** The 0-based index of this log within its tx (across both private and public logs for the tx). */
+    logIndexWithinTx: number;
+};
+/**
+ * A single log returned from {@link L2LogsSource.getPrivateLogsByTags} or {@link L2LogsSource.getPublicLogsByTags}.
+ *
+ * Generic over the include-options so that flagged fields become required when the caller passes a
+ * literal `true`. The default type argument ({@link LogIncludeOptions}) yields the widest shape
+ * (all include-fields optional) — this is what the JSON-RPC wire layer validates against.
+ *
+ * `logData` is the raw field-element payload, with the tag in field 0 (consumers slice it off).
+ *
+ * @example
+ * const l: LogResult<{ includeEffects: true }> = (await node.getPrivateLogsByTags({ tags, includeEffects: true }))[0][0];
+ * l.nullifiers; // required, not optional
+ */
+export type LogResult<Opts extends LogIncludeOptions = LogIncludeOptions> = Prettify<LogResultBase & PickIfFlag<LogIncludeOptions, Opts, 'includeEffects', {
+    noteHashes: Fr[];
+    nullifiers: Fr[];
+}>>;
+/** Zod schema for the widest {@link LogResult} shape (all include-gated fields optional). */
+export declare const LogResultSchema: z.ZodType<LogResult>;
+/** Builds a random {@link LogResult} for tests. `includeEffects` populates `noteHashes` + `nullifiers`. */
+export declare function randomLogResult(includeEffects?: boolean): LogResult;
+/** Human-readable single-line representation, primarily for the CLI `get-logs` command. */
+export declare function logResultToHumanReadable(log: LogResult): string;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibG9nX3Jlc3VsdC5kLnRzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2xvZ3MvbG9nX3Jlc3VsdC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsV0FBVyxFQUFxQixNQUFNLGlDQUFpQyxDQUFDO0FBRWpGLE9BQU8sRUFBRSxFQUFFLEVBQUUsTUFBTSxnQ0FBZ0MsQ0FBQztBQUVwRCxPQUFPLEtBQUssRUFBRSxVQUFVLEVBQUUsUUFBUSxFQUFFLE1BQU0seUJBQXlCLENBQUM7QUFFcEUsT0FBTyxFQUFFLENBQUMsRUFBRSxNQUFNLEtBQUssQ0FBQztBQUV4QixPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFFbkQsT0FBTyxFQUFFLE1BQU0sRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBQzFDLE9BQU8sS0FBSyxFQUFFLE1BQU0sRUFBRSxNQUFNLG9CQUFvQixDQUFDO0FBRWpELDhEQUE4RDtBQUM5RCxNQUFNLE1BQU0saUJBQWlCLEdBQUc7SUFDOUIsb0dBQW9HO0lBQ3BHLGNBQWMsQ0FBQyxFQUFFLE9BQU8sQ0FBQztDQUMxQixDQUFDO0FBRUYsZUFBTyxNQUFNLHVCQUF1QixFQUFFLENBQUMsQ0FBQyxPQUFPLENBQUMsaUJBQWlCLENBRS9ELENBQUM7QUFFSCwrREFBK0Q7QUFDL0QsTUFBTSxNQUFNLGFBQWEsR0FBRztJQUMxQixxRUFBcUU7SUFDckUsT0FBTyxFQUFFLEVBQUUsRUFBRSxDQUFDO0lBQ2QseUNBQXlDO0lBQ3pDLFdBQVcsRUFBRSxXQUFXLENBQUM7SUFDekIscURBQXFEO0lBQ3JELFNBQVMsRUFBRSxTQUFTLENBQUM7SUFDckIsMERBQTBEO0lBQzFELGNBQWMsRUFBRSxNQUFNLENBQUM7SUFDdkIsa0RBQWtEO0lBQ2xELE1BQU0sRUFBRSxNQUFNLENBQUM7SUFDZiwyREFBMkQ7SUFDM0Qsa0JBQWtCLEVBQUUsTUFBTSxDQUFDO0lBQzNCLG9HQUFvRztJQUNwRyxnQkFBZ0IsRUFBRSxNQUFNLENBQUM7Q0FDMUIsQ0FBQztBQUVGOzs7Ozs7Ozs7Ozs7R0FZRztBQUNILE1BQU0sTUFBTSxTQUFTLENBQUMsSUFBSSxTQUFTLGlCQUFpQixHQUFHLGlCQUFpQixJQUFJLFFBQVEsQ0FDbEYsYUFBYSxHQUFHLFVBQVUsQ0FBQyxpQkFBaUIsRUFBRSxJQUFJLEVBQUUsZ0JBQWdCLEVBQUU7SUFBRSxVQUFVLEVBQUUsRUFBRSxFQUFFLENBQUM7SUFBQyxVQUFVLEVBQUUsRUFBRSxFQUFFLENBQUE7Q0FBRSxDQUFDLENBQzlHLENBQUM7QUFFRiw2RkFBNkY7QUFDN0YsZUFBTyxNQUFNLGVBQWUsRUFBRSxDQUFDLENBQUMsT0FBTyxDQUFDLFNBQVMsQ0FVL0MsQ0FBQztBQUVILDJHQUEyRztBQUMzRyx3QkFBZ0IsZUFBZSxDQUFDLGNBQWMsVUFBUSxHQUFHLFNBQVMsQ0FjakU7QUFFRCwyRkFBMkY7QUFDM0Ysd0JBQWdCLHdCQUF3QixDQUFDLEdBQUcsRUFBRSxTQUFTLEdBQUcsTUFBTSxDQWMvRCJ9

package/dest/logs/log_result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log_result.d.ts","sourceRoot":"","sources":["../../src/logs/log_result.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAqB,MAAM,iCAAiC,CAAC;AAEjF,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,oGAAoG;IACpG,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAE/D,CAAC;AAEH,+DAA+D;AAC/D,MAAM,MAAM,aAAa,GAAG;IAC1B,qEAAqE;IACrE,OAAO,EAAE,EAAE,EAAE,CAAC;IACd,yCAAyC;IACzC,WAAW,EAAE,WAAW,CAAC;IACzB,qDAAqD;IACrD,SAAS,EAAE,SAAS,CAAC;IACrB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oGAAoG;IACpG,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,CAAC,IAAI,SAAS,iBAAiB,GAAG,iBAAiB,IAAI,QAAQ,CAClF,aAAa,GAAG,UAAU,CAAC,iBAAiB,EAAE,IAAI,EAAE,gBAAgB,EAAE;IAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAAC,UAAU,EAAE,EAAE,EAAE,CAAA;CAAE,CAAC,CAC9G,CAAC;AAEF,6FAA6F;AAC7F,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAU/C,CAAC;AAEH,2GAA2G;AAC3G,wBAAgB,eAAe,CAAC,cAAc,UAAQ,GAAG,SAAS,CAcjE;AAED,2FAA2F;AAC3F,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAc/D"}

package/dest/logs/log_result.js

@@ -0,0 +1,56 @@
+import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
+import { times } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas as foundationSchemas } from '@aztec/foundation/schemas';
+import { z } from 'zod';
+import { BlockHash } from '../block/block_hash.js';
+import { schemas } from '../schemas/schemas.js';
+import { TxHash } from '../tx/tx_hash.js';
+export const LogIncludeOptionsSchema = z.object({
+    includeEffects: z.boolean().optional()
+});
+/** Zod schema for the widest {@link LogResult} shape (all include-gated fields optional). */ export const LogResultSchema = z.object({
+    logData: z.array(foundationSchemas.Fr),
+    blockNumber: BlockNumberSchema,
+    blockHash: BlockHash.schema,
+    blockTimestamp: schemas.UInt64,
+    txHash: TxHash.schema,
+    txIndexWithinBlock: schemas.Integer,
+    logIndexWithinTx: schemas.Integer,
+    noteHashes: z.array(foundationSchemas.Fr).optional(),
+    nullifiers: z.array(foundationSchemas.Fr).optional()
+});
+/** Builds a random {@link LogResult} for tests. `includeEffects` populates `noteHashes` + `nullifiers`. */ export function randomLogResult(includeEffects = false) {
+    const base = {
+        logData: times(3, Fr.random),
+        blockNumber: BlockNumber(Math.floor(Math.random() * 100000) + 1),
+        blockHash: BlockHash.random(),
+        blockTimestamp: BigInt(Math.floor(Date.now() / 1000)),
+        txHash: TxHash.random(),
+        txIndexWithinBlock: Math.floor(Math.random() * 100),
+        logIndexWithinTx: Math.floor(Math.random() * 100)
+    };
+    if (includeEffects) {
+        return {
+            ...base,
+            noteHashes: times(3, Fr.random),
+            nullifiers: times(3, Fr.random)
+        };
+    }
+    return base;
+}
+/** Human-readable single-line representation, primarily for the CLI `get-logs` command. */ export function logResultToHumanReadable(log) {
+    const head = `block ${log.blockNumber} (${log.blockHash.toString()}) ` + `tx ${log.txHash.toString()} txIndex ${log.txIndexWithinBlock} logIndex ${log.logIndexWithinTx} ` + `ts ${log.blockTimestamp}`;
+    const data = `data [${log.logData.map((f)=>f.toString()).join(', ')}]`;
+    const parts = [
+        head,
+        data
+    ];
+    if (log.noteHashes !== undefined) {
+        parts.push(`noteHashes [${log.noteHashes.map((f)=>f.toString()).join(', ')}]`);
+    }
+    if (log.nullifiers !== undefined) {
+        parts.push(`nullifiers [${log.nullifiers.map((f)=>f.toString()).join(', ')}]`);
+    }
+    return parts.join(' | ');
+}