@aztec/stdlib 0.0.0-test.1 → 0.0.1-commit.017a351

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,0BAA0B,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAqB,MAAM,6BAA6B,CAAC;AAE3F,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,gBAAgB;IAOR,eAAe,EAAE,YAAY;IAAS,MAAM,EAAE,EAAE,EAAE;IANrE,MAAM,CAAC,aAAa,SAAwD;IAErE,kBAAkB,CAAC,EAAE,EAAE,GAAG,SAAS,CAAC;gBAIxB,eAAe,EAAE,YAAY,EAAS,MAAM,EAAE,EAAE,EAAE;IAQrE,QAAQ,IAAI,EAAE,EAAE;IAIhB,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,WAAW;IAU5C,OAAO;IAIP,MAAM,CAAC,KAAK;IAIZ,QAAQ,IAAI,MAAM;IAIlB,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;IAW/C,KAAK;WAIQ,MAAM;IAWnB,gBAAgB;IAOhB,gBAAgB;IAKhB,qBAAqB,CAAC,KAAK,EAAE,EAAE;IAI/B,UAAU;IAQJ,IAAI;IAUJ,IAAI;IAIV,MAAM,KAAK,MAAM;;;;;;;;;;;;OAOhB;IAED,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM;CAK3B"}
+{"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,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,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

@@ -1,125 +1,184 @@
-import { CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS, CONTRACT_CLASS_LOG_SIZE_IN_FIELDS } from '@aztec/constants';
-import { poseidon2Hash } from '@aztec/foundation/crypto';
-import { Fr } from '@aztec/foundation/fields';
+var _computedKey;
+import { CONTRACT_CLASS_LOG_LENGTH, CONTRACT_CLASS_LOG_SIZE_IN_FIELDS } from '@aztec/constants';
+import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
-import { BufferReader, FieldReader, serializeToBuffer } 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';
-export class ContractClassLog {
-    contractAddress;
+export class ContractClassLogFields {
     fields;
-    static SIZE_IN_BYTES = Fr.SIZE_IN_BYTES * CONTRACT_CLASS_LOG_SIZE_IN_FIELDS;
-    // Keeps original first field pre-siloing. Only set by silo().
-    unsiloedFirstField;
     // Below line gives error 'Type instantiation is excessively deep and possibly infinite. ts(2589)'
-    // public fields: Tuple<Fr, typeof CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS>
-    constructor(contractAddress, fields){
-        this.contractAddress = contractAddress;
+    // public fields: Tuple<Fr, typeof CONTRACT_CLASS_LOG_SIZE_IN_FIELDS>
+    constructor(fields){
         this.fields = fields;
-        if (fields.length !== CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS) {
-            throw new Error(`Invalid number of fields for ContractClassLog. Expected ${CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS}, got ${fields.length}`);
+        if (fields.length !== CONTRACT_CLASS_LOG_SIZE_IN_FIELDS) {
+            throw new Error(`Invalid number of fields for ContractClassLog. Expected ${CONTRACT_CLASS_LOG_SIZE_IN_FIELDS}, got ${fields.length}`);
+        }
+    }
+    static get schema() {
+        return z.object({
+            fields: z.array(schemas.Fr).refine((arr)=>arr.length === CONTRACT_CLASS_LOG_SIZE_IN_FIELDS)
+        }).transform(({ fields })=>new ContractClassLogFields(fields));
+    }
+    /**
+   * Creates a ContractClassLogFields from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing ContractClassLogFields fields
+   * @returns A ContractClassLogFields instance
+   */ static fromPlainObject(obj) {
+        if (obj instanceof ContractClassLogFields) {
+            return obj;
         }
+        return new ContractClassLogFields(obj.fields.map((f)=>Fr.fromPlainObject(f)));
     }
     toFields() {
-        return [
-            this.contractAddress.toField(),
-            ...this.fields
-        ];
+        return this.fields;
     }
     static fromFields(fields) {
         const reader = FieldReader.asReader(fields);
         // Below line gives error 'Type instantiation is excessively deep and possibly infinite. ts(2589)'
-        // return new ContractClassLog(reader.readFieldArray(CONTRACT_CLASS_LOG_SIZE_IN_FIELDS));
-        return new ContractClassLog(reader.readObject(AztecAddress), Array.from({
-            length: CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS
+        // reader.readFieldArray(CONTRACT_CLASS_LOG_LENGTH);
+        return new ContractClassLogFields(Array.from({
+            length: CONTRACT_CLASS_LOG_SIZE_IN_FIELDS
         }, ()=>reader.readField()));
     }
+    toBuffer(sink) {
+        if (!sink) {
+            return BufferSink.serialize(this);
+        }
+        serializeToSink(sink, this.fields);
+    }
+    static fromBuffer(buffer) {
+        const reader = BufferReader.asReader(buffer);
+        // Below line gives error 'Type instantiation is excessively deep and possibly infinite. ts(2589)'
+        // reader.readArray(CONTRACT_CLASS_LOG_SIZE_IN_FIELDS, Fr)
+        return new ContractClassLogFields(Array.from({
+            length: CONTRACT_CLASS_LOG_SIZE_IN_FIELDS
+        }, ()=>reader.readObject(Fr)));
+    }
+    equals(other) {
+        return this.fields.every((f, i)=>f.equals(other.fields[i]));
+    }
+    getEmittedFields(emittedLength) {
+        return this.fields.slice(0, emittedLength);
+    }
+    static fromEmittedFields(emittedFields) {
+        return new ContractClassLogFields(emittedFields.concat(Array(CONTRACT_CLASS_LOG_SIZE_IN_FIELDS - emittedFields.length).fill(Fr.ZERO)));
+    }
     isEmpty() {
         return this.fields.every((f)=>f.isZero());
     }
     static empty() {
-        return new ContractClassLog(AztecAddress.ZERO, new Array(CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS).fill(Fr.ZERO));
+        return new ContractClassLogFields(Array(CONTRACT_CLASS_LOG_SIZE_IN_FIELDS).fill(Fr.ZERO));
+    }
+    static random(emittedLength = CONTRACT_CLASS_LOG_SIZE_IN_FIELDS) {
+        return new ContractClassLogFields(Array.from({
+            length: emittedLength
+        }, ()=>Fr.random()).concat(Array(CONTRACT_CLASS_LOG_SIZE_IN_FIELDS - emittedLength).fill(Fr.ZERO)));
+    }
+    async hash() {
+        return await poseidon2Hash(this.fields);
+    }
+    clone() {
+        return ContractClassLogFields.fromBuffer(this.toBuffer());
+    }
+}
+_computedKey = inspect.custom;
+export class ContractClassLog {
+    contractAddress;
+    fields;
+    emittedLength;
+    static SIZE_IN_BYTES = Fr.SIZE_IN_BYTES * CONTRACT_CLASS_LOG_LENGTH;
+    constructor(contractAddress, fields, emittedLength){
+        this.contractAddress = contractAddress;
+        this.fields = fields;
+        this.emittedLength = emittedLength;
     }
-    toBuffer() {
-        return serializeToBuffer([
+    static from(fields) {
+        return new ContractClassLog(fields.contractAddress, fields.fields, fields.emittedLength);
+    }
+    toFields() {
+        return serializeToFields([
             this.contractAddress,
-            this.fields
+            this.fields,
+            this.emittedLength
         ]);
     }
+    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);
+    }
+    toBlobFields() {
+        return [
+            this.contractAddress.toField()
+        ].concat(this.getEmittedFields());
+    }
+    static fromBlobFields(emittedLength, fields) {
+        const reader = FieldReader.asReader(fields);
+        const contractAddress = reader.readObject(AztecAddress);
+        const emittedFields = reader.readFieldArray(emittedLength);
+        return new ContractClassLog(contractAddress, ContractClassLogFields.fromEmittedFields(emittedFields), emittedLength);
+    }
+    isEmpty() {
+        return this.contractAddress.isZero() && this.fields.isEmpty() && this.emittedLength === 0;
+    }
+    static empty() {
+        return new ContractClassLog(AztecAddress.ZERO, ContractClassLogFields.empty(), 0);
+    }
+    toBuffer(sink) {
+        if (!sink) {
+            return BufferSink.serialize(this);
+        }
+        serializeToSink(sink, this.contractAddress, this.fields, this.emittedLength);
+    }
     static fromBuffer(buffer) {
         const reader = BufferReader.asReader(buffer);
-        // Below line gives error 'Type instantiation is excessively deep and possibly infinite. ts(2589)'
-        // reader.readArray(CONTRACT_CLASS_LOG_SIZE_IN_FIELDS, Fr);
         const address = reader.readObject(AztecAddress);
-        const fields = Array.from({
-            length: CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS
-        }, ()=>reader.remainingBytes() == 0 ? Fr.ZERO : Fr.fromBuffer(reader));
-        return new ContractClassLog(address, fields);
-    }
-    clone() {
-        return ContractClassLog.fromBuffer(this.toBuffer());
+        const fields = ContractClassLogFields.fromBuffer(reader);
+        const emittedLength = reader.readNumber();
+        return new ContractClassLog(address, fields, emittedLength);
     }
     static async random() {
         // NB: Using half the maximum number of fields per log because max fields keeps overfilling blobs in tests.
-        // Below line gives error 'Type instantiation is excessively deep and possibly infinite. ts(2589)'
-        // makeTuple(CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS, Fr.random);
-        const fields = Array.from({
-            length: Math.ceil(CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS / 2)
-        }, ()=>Fr.random());
-        return new ContractClassLog(await AztecAddress.random(), fields.concat(Array.from({
-            length: Math.floor(CONTRACT_CLASS_LOG_DATA_SIZE_IN_FIELDS / 2)
-        }, ()=>Fr.ZERO)));
-    }
-    getEmittedLength() {
-        // This assumes that we cut trailing zeroes from the end of the log. In ts, these will always be added back.
-        // Does not include address or length prefix.
-        // Note: Unlike public logs, address is not included here because it is not included in the log itself.
-        return this.getEmittedFields().length;
-    }
-    getEmittedFields() {
-        const lastNonZeroIndex = this.fields.findLastIndex((f)=>!f.isZero());
-        return this.fields.slice(0, lastNonZeroIndex + 1);
-    }
-    setUnsiloedFirstField(field) {
-        this.unsiloedFirstField = field;
-    }
-    toUnsiloed() {
-        if (this.unsiloedFirstField) {
-            return new ContractClassLog(this.contractAddress, [
-                this.unsiloedFirstField
-            ].concat(this.fields.slice(1)));
-        } else {
-            return this;
-        }
-    }
-    async silo() {
-        const innerLog = this.clone();
-        if (innerLog.contractAddress.isZero()) {
-            return innerLog;
-        }
-        innerLog.setUnsiloedFirstField(innerLog.fields[0]);
-        innerLog.fields[0] = await poseidon2Hash([
-            innerLog.contractAddress,
-            innerLog.fields[0]
-        ]);
-        return innerLog;
+        const emittedLength = Math.ceil(CONTRACT_CLASS_LOG_SIZE_IN_FIELDS / 2);
+        return new ContractClassLog(await AztecAddress.random(), ContractClassLogFields.random(emittedLength), emittedLength);
     }
     async hash() {
-        return await poseidon2Hash(this.fields);
+        return await this.fields.hash();
     }
     static get schema() {
         return z.object({
             contractAddress: AztecAddress.schema,
-            fields: z.array(schemas.Fr)
-        }).transform(({ contractAddress, fields })=>ContractClassLog.fromFields([
-                contractAddress.toField(),
-                ...fields
-            ]));
+            fields: ContractClassLogFields.schema,
+            emittedLength: z.number()
+        }).transform(ContractClassLog.from);
+    }
+    /**
+   * Creates a ContractClassLog from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing ContractClassLog fields
+   * @returns A ContractClassLog instance
+   */ static fromPlainObject(obj) {
+        if (obj instanceof ContractClassLog) {
+            return obj;
+        }
+        return new ContractClassLog(AztecAddress.fromPlainObject(obj.contractAddress), ContractClassLogFields.fromPlainObject(obj.fields), obj.emittedLength);
     }
-    [inspect.custom]() {
+    [_computedKey]() {
         return `ContractClassLog {
-      fields: [${this.fields.map((x)=>inspect(x)).join(', ')}],
+      contractAddress: ${this.contractAddress.toString()},
+      emittedLength: ${this.emittedLength},
+      fields: [${this.fields.fields.map((x)=>inspect(x)).join(', ')}],
     }`;
     }
 }

package/dest/logs/debug_log.d.ts

@@ -0,0 +1,21 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { type LogLevel } from '@aztec/foundation/log';
+import { type ZodFor } from '@aztec/foundation/schemas';
+import { AztecAddress } from '../aztec-address/index.js';
+export declare class DebugLog {
+    contractAddress: AztecAddress;
+    level: LogLevel;
+    message: string;
+    fields: Fr[];
+    constructor(contractAddress: AztecAddress, level: LogLevel, message: string, fields: Fr[]);
+    static get schema(): ZodFor<DebugLog>;
+    /**
+     * Creates a DebugLog from a plain object without Zod validation.
+     * This method is optimized for performance and skips validation, making it suitable
+     * for deserializing trusted data (e.g., from C++ via MessagePack).
+     * @param obj - Plain object containing DebugLog fields
+     * @returns A DebugLog instance
+     */
+    static fromPlainObject(obj: any): DebugLog;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVidWdfbG9nLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbG9ncy9kZWJ1Z19sb2cudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLEVBQUUsRUFBRSxNQUFNLGdDQUFnQyxDQUFDO0FBQ3BELE9BQU8sRUFBRSxLQUFLLFFBQVEsRUFBYSxNQUFNLHVCQUF1QixDQUFDO0FBQ2pFLE9BQU8sRUFBRSxLQUFLLE1BQU0sRUFBVyxNQUFNLDJCQUEyQixDQUFDO0FBSWpFLE9BQU8sRUFBRSxZQUFZLEVBQUUsTUFBTSwyQkFBMkIsQ0FBQztBQUt6RCxxQkFBYSxRQUFRO0lBRVYsZUFBZSxFQUFFLFlBQVk7SUFDN0IsS0FBSyxFQUFFLFFBQVE7SUFDZixPQUFPLEVBQUUsTUFBTTtJQUNmLE1BQU0sRUFBRSxFQUFFLEVBQUU7SUFKckIsWUFDUyxlQUFlLEVBQUUsWUFBWSxFQUM3QixLQUFLLEVBQUUsUUFBUSxFQUNmLE9BQU8sRUFBRSxNQUFNLEVBQ2YsTUFBTSxFQUFFLEVBQUUsRUFBRSxFQUNqQjtJQUVKLE1BQU0sS0FBSyxNQUFNLElBQUksTUFBTSxDQUFDLFFBQVEsQ0FBQyxDQVdwQztJQUVEOzs7Ozs7T0FNRztJQUNILE1BQU0sQ0FBQyxlQUFlLENBQUMsR0FBRyxFQUFFLEdBQUcsR0FBRyxRQUFRLENBVXpDO0NBQ0YifQ==

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

@@ -0,0 +1 @@
+{"version":3,"file":"debug_log.d.ts","sourceRoot":"","sources":["../../src/logs/debug_log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,gCAAgC,CAAC;AACpD,OAAO,EAAE,KAAK,QAAQ,EAAa,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,2BAA2B,CAAC;AAIjE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAKzD,qBAAa,QAAQ;IAEV,eAAe,EAAE,YAAY;IAC7B,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,MAAM;IACf,MAAM,EAAE,EAAE,EAAE;IAJrB,YACS,eAAe,EAAE,YAAY,EAC7B,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,EAAE,EAAE,EACjB;IAEJ,MAAM,KAAK,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,CAWpC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,QAAQ,CAUzC;CACF"}

package/dest/logs/debug_log.js

@@ -0,0 +1,39 @@
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { LogLevels } from '@aztec/foundation/log';
+import { schemas } from '@aztec/foundation/schemas';
+import { z } from 'zod';
+import { AztecAddress } from '../aztec-address/index.js';
+/*
+ * Represents a debug log emitted by public bytecode.
+ */ export class DebugLog {
+    contractAddress;
+    level;
+    message;
+    fields;
+    constructor(contractAddress, level, message, fields){
+        this.contractAddress = contractAddress;
+        this.level = level;
+        this.message = message;
+        this.fields = fields;
+    }
+    static get schema() {
+        return z.object({
+            contractAddress: AztecAddress.schema,
+            level: z.enum(LogLevels),
+            message: z.string(),
+            fields: z.array(schemas.Fr)
+        }).transform(({ contractAddress, level, message, fields })=>new DebugLog(contractAddress, level, message, fields));
+    }
+    /**
+   * Creates a DebugLog from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing DebugLog fields
+   * @returns A DebugLog instance
+   */ static fromPlainObject(obj) {
+        if (obj instanceof DebugLog) {
+            return obj;
+        }
+        return new DebugLog(AztecAddress.fromPlainObject(obj.contractAddress), obj.level, obj.message, obj.fields.map((f)=>Fr.fromPlainObject(f)));
+    }
+}

package/dest/logs/debug_log_store.d.ts

@@ -0,0 +1,30 @@
+import type { TxReceipt } from '../tx/tx_receipt.js';
+import type { DebugLog } from './debug_log.js';
+/**
+ * Store for debug logs emitted by public functions during transaction execution.
+ *
+ * Uses the Null Object pattern: production code uses NullDebugLogStore (no-op), while test mode uses
+ * InMemoryDebugLogStore (stores and serves logs).
+ */
+export interface DebugLogStore {
+    /** Store debug logs for a processed transaction. */
+    storeLogs(txHash: string, logs: DebugLog[]): void;
+    /** Decorate a TxReceipt with any stored debug logs for the given tx. */
+    decorateReceiptWithLogs(txHash: string, receipt: TxReceipt): void;
+    /** Whether debug log collection is enabled. */
+    readonly isEnabled: boolean;
+}
+/** No-op implementation for production mode. */
+export declare class NullDebugLogStore implements DebugLogStore {
+    storeLogs(_txHash: string, _logs: DebugLog[]): void;
+    decorateReceiptWithLogs(_txHash: string, _receipt: TxReceipt): void;
+    get isEnabled(): boolean;
+}
+/** In-memory implementation for test mode that stores and serves debug logs. */
+export declare class InMemoryDebugLogStore implements DebugLogStore {
+    private map;
+    storeLogs(txHash: string, logs: DebugLog[]): void;
+    decorateReceiptWithLogs(txHash: string, receipt: TxReceipt): void;
+    get isEnabled(): boolean;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGVidWdfbG9nX3N0b3JlLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvbG9ncy9kZWJ1Z19sb2dfc3RvcmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEVBQUUsU0FBUyxFQUFFLE1BQU0scUJBQXFCLENBQUM7QUFDckQsT0FBTyxLQUFLLEVBQUUsUUFBUSxFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFL0M7Ozs7O0dBS0c7QUFDSCxNQUFNLFdBQVcsYUFBYTtJQUM1QixvREFBb0Q7SUFDcEQsU0FBUyxDQUFDLE1BQU0sRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFLFFBQVEsRUFBRSxHQUFHLElBQUksQ0FBQztJQUNsRCx3RUFBd0U7SUFDeEUsdUJBQXVCLENBQUMsTUFBTSxFQUFFLE1BQU0sRUFBRSxPQUFPLEVBQUUsU0FBUyxHQUFHLElBQUksQ0FBQztJQUNsRSwrQ0FBK0M7SUFDL0MsUUFBUSxDQUFDLFNBQVMsRUFBRSxPQUFPLENBQUM7Q0FDN0I7QUFFRCxnREFBZ0Q7QUFDaEQscUJBQWEsaUJBQWtCLFlBQVcsYUFBYTtJQUNyRCxTQUFTLENBQUMsT0FBTyxFQUFFLE1BQU0sRUFBRSxLQUFLLEVBQUUsUUFBUSxFQUFFLEdBQUcsSUFBSSxDQUVsRDtJQUNELHVCQUF1QixDQUFDLE9BQU8sRUFBRSxNQUFNLEVBQUUsUUFBUSxFQUFFLFNBQVMsR0FBRyxJQUFJLENBRWxFO0lBQ0QsSUFBSSxTQUFTLElBQUksT0FBTyxDQUV2QjtDQUNGO0FBRUQsZ0ZBQWdGO0FBQ2hGLHFCQUFhLHFCQUFzQixZQUFXLGFBQWE7SUFDekQsT0FBTyxDQUFDLEdBQUcsQ0FBaUM7SUFFNUMsU0FBUyxDQUFDLE1BQU0sRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFLFFBQVEsRUFBRSxHQUFHLElBQUksQ0FJaEQ7SUFFRCx1QkFBdUIsQ0FBQyxNQUFNLEVBQUUsTUFBTSxFQUFFLE9BQU8sRUFBRSxTQUFTLEdBQUcsSUFBSSxDQU9oRTtJQUVELElBQUksU0FBUyxJQUFJLE9BQU8sQ0FFdkI7Q0FDRiJ9

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

@@ -0,0 +1 @@
+{"version":3,"file":"debug_log_store.d.ts","sourceRoot":"","sources":["../../src/logs/debug_log_store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAClD,wEAAwE;IACxE,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAClE,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,gDAAgD;AAChD,qBAAa,iBAAkB,YAAW,aAAa;IACrD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,CAElD;IACD,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,GAAG,IAAI,CAElE;IACD,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAED,gFAAgF;AAChF,qBAAa,qBAAsB,YAAW,aAAa;IACzD,OAAO,CAAC,GAAG,CAAiC;IAE5C,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,CAIhD;IAED,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,IAAI,CAOhE;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF"}

package/dest/logs/debug_log_store.js

@@ -0,0 +1,30 @@
+/** No-op implementation for production mode. */ export class NullDebugLogStore {
+    storeLogs(_txHash, _logs) {
+        return;
+    }
+    decorateReceiptWithLogs(_txHash, _receipt) {
+        return;
+    }
+    get isEnabled() {
+        return false;
+    }
+}
+/** In-memory implementation for test mode that stores and serves debug logs. */ export class InMemoryDebugLogStore {
+    map = new Map();
+    storeLogs(txHash, logs) {
+        if (logs.length > 0) {
+            this.map.set(txHash, logs);
+        }
+    }
+    decorateReceiptWithLogs(txHash, receipt) {
+        if (receipt.isMined()) {
+            const debugLogs = this.map.get(txHash);
+            if (debugLogs) {
+                receipt.debugLogs = debugLogs;
+            }
+        }
+    }
+    get isEnabled() {
+        return true;
+    }
+}

package/dest/logs/index.d.ts

@@ -1,12 +1,19 @@
-export * from './log_with_tx_data.js';
-export * from './indexed_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 './log_id.js';
-export * from './log_filter.js';
-export * from './extended_public_log.js';
-export * from './extended_contract_class_log.js';
-export * from './l1_payload/index.js';
-export * from './tx_scoped_l2_log.js';
-//# sourceMappingURL=index.d.ts.map
+export * from './pending_tagged_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 './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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9sb2dzL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsOEJBQThCLENBQUM7QUFDN0MsY0FBYyx5QkFBeUIsQ0FBQztBQUN4QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLCtCQUErQixDQUFDO0FBQzlDLGNBQWMsc0JBQXNCLENBQUM7QUFDckMsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsaUJBQWlCLENBQUMifQ==

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,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,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,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC"}

package/dest/logs/index.js

@@ -1,11 +1,18 @@
-export * from './log_with_tx_data.js';
-export * from './indexed_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 './log_id.js';
-export * from './log_filter.js';
-export * from './extended_public_log.js';
-export * from './extended_contract_class_log.js';
-export * from './l1_payload/index.js';
-export * from './tx_scoped_l2_log.js';
+export * from './pending_tagged_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 './message_context.js';
+export * from './debug_log.js';
+export * from './debug_log_store.js';
+export * from './tag.js';
+export * from './siloed_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);
+    }
+}