@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/block/l2_block_downloader/l2_block_stream.ts

@@ -0,0 +1,179 @@
+import { AbortError } from '@aztec/foundation/error';
+import { createLogger } from '@aztec/foundation/log';
+import { RunningPromise } from '@aztec/foundation/running-promise';
+
+import type { L2Block } from '../l2_block.js';
+import type { L2BlockId, L2BlockSource, L2Tips } from '../l2_block_source.js';
+
+/** Creates a stream of events for new blocks, chain tips updates, and reorgs, out of polling an archiver or a node. */
+export class L2BlockStream {
+  private readonly runningPromise: RunningPromise;
+  private isSyncing = false;
+
+  constructor(
+    private l2BlockSource: Pick<L2BlockSource, 'getBlocks' | 'getBlockHeader' | 'getL2Tips'>,
+    private localData: L2BlockStreamLocalDataProvider,
+    private handler: L2BlockStreamEventHandler,
+    private readonly log = createLogger('types:block_stream'),
+    private opts: {
+      proven?: boolean;
+      pollIntervalMS?: number;
+      batchSize?: number;
+      startingBlock?: number;
+    } = {},
+  ) {
+    this.runningPromise = new RunningPromise(() => this.work(), log, this.opts.pollIntervalMS ?? 1000);
+  }
+
+  public start() {
+    this.log.verbose(`Starting L2 block stream`, this.opts);
+    this.runningPromise.start();
+  }
+
+  public async stop() {
+    await this.runningPromise.stop();
+  }
+
+  public isRunning() {
+    return this.runningPromise.isRunning();
+  }
+
+  public async sync() {
+    this.isSyncing = true;
+    await this.runningPromise.trigger();
+    this.isSyncing = false;
+  }
+
+  protected async work() {
+    try {
+      const sourceTips = await this.l2BlockSource.getL2Tips();
+      const localTips = await this.localData.getL2Tips();
+      this.log.trace(`Running L2 block stream`, {
+        sourceLatest: sourceTips.latest.number,
+        localLatest: localTips.latest.number,
+        sourceFinalized: sourceTips.finalized.number,
+        localFinalized: localTips.finalized.number,
+        sourceProven: sourceTips.proven.number,
+        localProven: localTips.proven.number,
+        sourceLatestHash: sourceTips.latest.hash,
+        localLatestHash: localTips.latest.hash,
+        sourceProvenHash: sourceTips.proven.hash,
+        localProvenHash: localTips.proven.hash,
+        sourceFinalizedHash: sourceTips.finalized.hash,
+        localFinalizedHash: localTips.finalized.hash,
+      });
+
+      // Check if there was a reorg and emit a chain-pruned event if so.
+      let latestBlockNumber = localTips.latest.number;
+      while (!(await this.areBlockHashesEqualAt(latestBlockNumber, { sourceCache: [sourceTips.latest] }))) {
+        latestBlockNumber--;
+      }
+      if (latestBlockNumber < localTips.latest.number) {
+        this.log.verbose(`Reorg detected. Pruning blocks from ${latestBlockNumber + 1} to ${localTips.latest.number}.`);
+        await this.emitEvent({ type: 'chain-pruned', blockNumber: latestBlockNumber });
+      }
+
+      // If we are just starting, use the starting block number from the options.
+      if (latestBlockNumber === 0 && this.opts.startingBlock !== undefined) {
+        latestBlockNumber = Math.max(this.opts.startingBlock - 1, 0);
+        this.log.verbose(`Starting sync from block number ${latestBlockNumber}`);
+      }
+
+      // Request new blocks from the source.
+      while (latestBlockNumber < sourceTips.latest.number) {
+        const from = latestBlockNumber + 1;
+        const limit = Math.min(this.opts.batchSize ?? 20, sourceTips.latest.number - from + 1);
+        this.log.trace(`Requesting blocks from ${from} limit ${limit} proven=${this.opts.proven}`);
+        const blocks = await this.l2BlockSource.getBlocks(from, limit, this.opts.proven);
+        if (blocks.length === 0) {
+          break;
+        }
+        await this.emitEvent({ type: 'blocks-added', blocks });
+        latestBlockNumber = blocks.at(-1)!.number;
+      }
+
+      // Update the proven and finalized tips.
+      // TODO(palla/reorg): Should we emit this before passing the new blocks? This would allow world-state to skip
+      // building the data structures for the pending chain if it's unneeded.
+      if (localTips.proven !== undefined && sourceTips.proven.number !== localTips.proven.number) {
+        await this.emitEvent({ type: 'chain-proven', blockNumber: sourceTips.proven.number });
+      }
+      if (localTips.finalized !== undefined && sourceTips.finalized.number !== localTips.finalized.number) {
+        await this.emitEvent({ type: 'chain-finalized', blockNumber: sourceTips.finalized.number });
+      }
+    } catch (err: any) {
+      if (err.name === 'AbortError') {
+        return;
+      }
+      this.log.error(`Error processing block stream`, err);
+    }
+  }
+
+  /**
+   * Returns whether the source and local agree on the block hash at a given height.
+   * @param blockNumber - The block number to test.
+   * @param args - A cache of data already requested from source, to avoid re-requesting it.
+   */
+  private async areBlockHashesEqualAt(blockNumber: number, args: { sourceCache: L2BlockId[] }) {
+    if (blockNumber === 0) {
+      return true;
+    }
+    const localBlockHash = await this.localData.getL2BlockHash(blockNumber);
+    const sourceBlockHash =
+      args.sourceCache.find(id => id.number === blockNumber && id.hash)?.hash ??
+      (await this.l2BlockSource
+        .getBlockHeader(blockNumber)
+        .then(h => h?.hash())
+        .then(hash => hash?.toString()));
+    this.log.trace(`Comparing block hashes for block ${blockNumber}`, {
+      localBlockHash,
+      sourceBlockHash,
+      sourceCacheNumber: args.sourceCache[0]?.number,
+      sourceCacheHash: args.sourceCache[0]?.hash,
+    });
+    return localBlockHash === sourceBlockHash;
+  }
+
+  private async emitEvent(event: L2BlockStreamEvent) {
+    this.log.debug(
+      `Emitting ${event.type} (${event.type === 'blocks-added' ? event.blocks.length : event.blockNumber})`,
+    );
+    await this.handler.handleBlockStreamEvent(event);
+    if (!this.isRunning() && !this.isSyncing) {
+      throw new AbortError();
+    }
+  }
+}
+
+/** Interface to the local view of the chain. Implemented by world-state and l2-tips-store. */
+export interface L2BlockStreamLocalDataProvider {
+  getL2BlockHash(number: number): Promise<string | undefined>;
+  getL2Tips(): Promise<L2Tips>;
+}
+
+/** Interface to a handler of events emitted. */
+export interface L2BlockStreamEventHandler {
+  handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void>;
+}
+
+export type L2BlockStreamEvent =
+  | {
+      type: 'blocks-added';
+      /** New blocks added to the chain. */
+      blocks: L2Block[];
+    }
+  | {
+      type: 'chain-pruned';
+      /** Last correct block number (new tip of the unproven chain). */
+      blockNumber: number;
+    }
+  | {
+      type: 'chain-proven';
+      /** New proven block number */
+      blockNumber: number;
+    }
+  | {
+      type: 'chain-finalized';
+      /** New finalized block number */
+      blockNumber: number;
+    };

package/src/block/l2_block_number.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+import { schemas } from '../schemas/index.js';
+
+export const L2BlockNumberSchema = z.union([schemas.Integer, z.literal('latest')]);
+
+/** Helper type for a specific L2 block number or the latest block number */
+export type L2BlockNumber = z.infer<typeof L2BlockNumberSchema>;

package/src/block/l2_block_source.ts

@@ -0,0 +1,148 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+
+import { z } from 'zod';
+
+import type { L1RollupConstants } from '../epoch-helpers/index.js';
+import type { BlockHeader } from '../tx/block_header.js';
+import type { TxEffect } from '../tx/tx_effect.js';
+import type { TxHash } from '../tx/tx_hash.js';
+import type { TxReceipt } from '../tx/tx_receipt.js';
+import type { InBlock } from './in_block.js';
+import type { L2Block } from './l2_block.js';
+
+/**
+ * Interface of classes allowing for the retrieval of L2 blocks.
+ */
+export interface L2BlockSource {
+  /**
+   * Method to fetch the rollup contract address at the base-layer.
+   * @returns The rollup address.
+   */
+  getRollupAddress(): Promise<EthAddress>;
+
+  /**
+   * Method to fetch the registry contract address at the base-layer.
+   * @returns The registry address.
+   */
+  getRegistryAddress(): Promise<EthAddress>;
+
+  /**
+   * Gets the number of the latest L2 block processed by the block source implementation.
+   * @returns The number of the latest L2 block processed by the block source implementation.
+   */
+  getBlockNumber(): Promise<number>;
+
+  /**
+   * Gets the number of the latest L2 block proven seen by the block source implementation.
+   * @returns The number of the latest L2 block proven seen by the block source implementation.
+   */
+  getProvenBlockNumber(): Promise<number>;
+
+  /**
+   * Gets the number of the latest L2 proven epoch seen by the block source implementation.
+   * @returns The number of the latest L2 proven epoch seen by the block source implementation.
+   */
+  getProvenL2EpochNumber(): Promise<number | undefined>;
+
+  /**
+   * Gets an l2 block. If a negative number is passed, the block returned is the most recent.
+   * @param number - The block number to return (inclusive).
+   * @returns The requested L2 block.
+   */
+  getBlock(number: number): Promise<L2Block | undefined>;
+
+  /**
+   * Gets an l2 block header.
+   * @param number - The block number to return or 'latest' for the most recent one.
+   * @returns The requested L2 block header.
+   */
+  getBlockHeader(number: number | 'latest'): Promise<BlockHeader | undefined>;
+
+  /**
+   * Gets up to `limit` amount of L2 blocks starting from `from`.
+   * @param from - Number of the first block to return (inclusive).
+   * @param limit - The maximum number of blocks to return.
+   * @param proven - If true, only return blocks that have been proven.
+   * @returns The requested L2 blocks.
+   */
+  getBlocks(from: number, limit: number, proven?: boolean): Promise<L2Block[]>;
+
+  /**
+   * Gets a tx effect.
+   * @param txHash - The hash of a transaction which resulted in the returned tx effect.
+   * @returns The requested tx effect.
+   */
+  getTxEffect(txHash: TxHash): Promise<InBlock<TxEffect> | undefined>;
+
+  /**
+   * Gets a receipt of a settled tx.
+   * @param txHash - The hash of a tx we try to get the receipt for.
+   * @returns The requested tx receipt (or undefined if not found).
+   */
+  getSettledTxReceipt(txHash: TxHash): Promise<TxReceipt | undefined>;
+
+  /**
+   * Returns the current L2 slot number based on the current L1 timestamp.
+   */
+  getL2SlotNumber(): Promise<bigint>;
+
+  /**
+   * Returns the current L2 epoch number based on the current L1 timestamp.
+   */
+  getL2EpochNumber(): Promise<bigint>;
+
+  /**
+   * Returns all blocks for a given epoch.
+   * @dev Use this method only with recent epochs, since it walks the block list backwards.
+   * @param epochNumber - The epoch number to return blocks for.
+   */
+  getBlocksForEpoch(epochNumber: bigint): Promise<L2Block[]>;
+
+  /**
+   * Returns whether the given epoch is completed on L1, based on the current L1 and L2 block numbers.
+   * @param epochNumber - The epoch number to check.
+   */
+  isEpochComplete(epochNumber: bigint): Promise<boolean>;
+
+  /**
+   * Returns the tips of the L2 chain.
+   */
+  getL2Tips(): Promise<L2Tips>;
+
+  /**
+   * Returns the rollup constants for the current chain.
+   */
+  getL1Constants(): Promise<L1RollupConstants>;
+}
+
+/**
+ * Identifier for L2 block tags.
+ * - latest: Latest block pushed to L1.
+ * - proven: Proven block on L1.
+ * - finalized: Proven block on a finalized L1 block (not implemented, set to proven for now).
+ */
+export type L2BlockTag = 'latest' | 'proven' | 'finalized';
+
+/** Tips of the L2 chain. */
+export type L2Tips = Record<L2BlockTag, L2BlockId>;
+
+/** Identifies a block by number and hash. */
+export type L2BlockId = z.infer<typeof L2BlockIdSchema>;
+
+// TODO(palla/schemas): This package should know what is the block hash of the genesis block 0.
+const L2BlockIdSchema = z.union([
+  z.object({
+    number: z.literal(0),
+    hash: z.undefined(),
+  }),
+  z.object({
+    number: z.number(),
+    hash: z.string(),
+  }),
+]);
+
+export const L2TipsSchema = z.object({
+  latest: L2BlockIdSchema,
+  proven: L2BlockIdSchema,
+  finalized: L2BlockIdSchema,
+}) satisfies z.ZodType<L2Tips>;

package/src/block/nullifier_with_block_source.ts

@@ -0,0 +1,7 @@
+import type { Fr } from '@aztec/foundation/fields';
+
+import type { InBlock } from './in_block.js';
+
+export interface NullifierWithBlockSource {
+  findNullifiersIndexesWithBlock(blockNumber: number, nullifiers: Fr[]): Promise<(InBlock<bigint> | undefined)[]>;
+}

package/src/config/config.ts

@@ -0,0 +1,42 @@
+import { l1ContractAddressesMapping } from '@aztec/ethereum/l1-contract-addresses';
+import { type ConfigMappingsType, numberConfigHelper } from '@aztec/foundation/config';
+import { EthAddress } from '@aztec/foundation/eth-address';
+
+export { type AllowedElement, type SequencerConfig, SequencerConfigSchema } from '../interfaces/configs.js';
+
+export const emptyChainConfig: ChainConfig = {
+  l1ChainId: 0,
+  l1Contracts: { rollupAddress: EthAddress.ZERO },
+  version: 0,
+};
+
+export const chainConfigMappings: ConfigMappingsType<ChainConfig> = {
+  l1ChainId: {
+    env: 'L1_CHAIN_ID',
+    parseEnv: (val: string) => +val,
+    defaultValue: 31337,
+    description: 'The chain ID of the ethereum host.',
+  },
+  version: {
+    env: 'VERSION',
+    description: 'The version of the rollup.',
+    ...numberConfigHelper(1),
+  },
+  l1Contracts: {
+    description: 'The deployed L1 contract addresses',
+    nested: l1ContractAddressesMapping,
+  },
+};
+
+/** Chain configuration. */
+export type ChainConfig = {
+  /** The chain id of the ethereum host. */
+  l1ChainId: number;
+  /** The version of the rollup. */
+  version: number;
+  /** The address to the L1 contracts. */
+  l1Contracts: {
+    /** The address to rollup */
+    rollupAddress: EthAddress;
+  };
+};

package/src/config/index.ts

@@ -0,0 +1 @@
+export * from './config.js';

package/src/contract/artifact_hash.ts

@@ -0,0 +1,115 @@
+import { sha256 } from '@aztec/foundation/crypto';
+import { Fr, reduceFn } from '@aztec/foundation/fields';
+import { createLogger } from '@aztec/foundation/log';
+import { numToUInt8 } from '@aztec/foundation/serialize';
+import { MerkleTree, MerkleTreeCalculator } from '@aztec/foundation/trees';
+
+import { type ContractArtifact, type FunctionArtifact, FunctionSelector, FunctionType } from '../abi/index.js';
+
+const VERSION = 1;
+
+// TODO(miranda): Artifact and artifact metadata hashes are currently the only SHAs not truncated by a byte.
+// They are never recalculated in the circuit or L1 contract, but they are input to circuits, so perhaps modding here is preferable?
+// TODO(@spalladino) Reducing sha256 to a field may have security implications. Validate this with crypto team.
+const sha256Fr = reduceFn(sha256, Fr);
+
+/**
+ * Returns the artifact hash of a given compiled contract artifact.
+ *
+ * ```
+ * private_functions_artifact_leaves = artifact.private_functions.map fn =>
+ *   sha256(fn.selector, fn.metadata_hash, sha256(fn.bytecode))
+ * private_functions_artifact_tree_root = merkleize(private_functions_artifact_leaves)
+ *
+ * unconstrained_functions_artifact_leaves = artifact.unconstrained_functions.map fn =>
+ *   sha256(fn.selector, fn.metadata_hash, sha256(fn.bytecode))
+ * unconstrained_functions_artifact_tree_root = merkleize(unconstrained_functions_artifact_leaves)
+ *
+ * version = 1
+ * artifact_hash = sha256(
+ *   version,
+ *   private_functions_artifact_tree_root,
+ *   unconstrained_functions_artifact_tree_root,
+ *   artifact_metadata,
+ * )
+ * ```
+ * @param artifact - Artifact to calculate the hash for.
+ */
+export async function computeArtifactHash(
+  artifact: ContractArtifact | { privateFunctionRoot: Fr; unconstrainedFunctionRoot: Fr; metadataHash: Fr },
+): Promise<Fr> {
+  if ('privateFunctionRoot' in artifact && 'unconstrainedFunctionRoot' in artifact && 'metadataHash' in artifact) {
+    const { privateFunctionRoot, unconstrainedFunctionRoot, metadataHash } = artifact;
+    const preimage = [privateFunctionRoot, unconstrainedFunctionRoot, metadataHash].map(x => x.toBuffer());
+    return sha256Fr(Buffer.concat([numToUInt8(VERSION), ...preimage]));
+  }
+
+  const preimage = await computeArtifactHashPreimage(artifact);
+  const artifactHash = computeArtifactHash(preimage);
+  getLogger().trace('Computed artifact hash', { artifactHash, ...preimage });
+  return artifactHash;
+}
+
+export async function computeArtifactHashPreimage(artifact: ContractArtifact) {
+  const privateFunctionRoot = await computeArtifactFunctionTreeRoot(artifact, FunctionType.PRIVATE);
+  const unconstrainedFunctionRoot = await computeArtifactFunctionTreeRoot(artifact, FunctionType.UNCONSTRAINED);
+  const metadataHash = computeArtifactMetadataHash(artifact);
+  return { privateFunctionRoot, unconstrainedFunctionRoot, metadataHash };
+}
+
+export function computeArtifactMetadataHash(artifact: ContractArtifact) {
+  return sha256Fr(Buffer.from(JSON.stringify({ name: artifact.name, outputs: artifact.outputs }), 'utf-8'));
+}
+
+export async function computeArtifactFunctionTreeRoot(artifact: ContractArtifact, fnType: FunctionType) {
+  const tree = await computeArtifactFunctionTree(artifact, fnType);
+  return tree?.root ? Fr.fromBuffer(tree.root) : Fr.ZERO;
+}
+
+export async function computeArtifactFunctionTree(
+  artifact: ContractArtifact,
+  fnType: FunctionType,
+): Promise<MerkleTree | undefined> {
+  const leaves = await computeFunctionLeaves(artifact, fnType);
+  // TODO(@spalladino) Consider implementing a null-object for empty trees
+  if (leaves.length === 0) {
+    return undefined;
+  }
+  const height = Math.ceil(Math.log2(leaves.length));
+  const calculator = await MerkleTreeCalculator.create(height, Buffer.alloc(32), getArtifactMerkleTreeHasher());
+  return calculator.computeTree(leaves.map(x => x.toBuffer()));
+}
+
+async function computeFunctionLeaves(artifact: ContractArtifact, fnType: FunctionType) {
+  const selectors = await Promise.all(
+    artifact.functions
+      .filter(f => f.functionType === fnType)
+      .map(async f => ({ ...f, selector: await FunctionSelector.fromNameAndParameters(f.name, f.parameters) })),
+  );
+  selectors.sort((a, b) => a.selector.value - b.selector.value);
+  return await Promise.all(selectors.map(computeFunctionArtifactHash));
+}
+
+export async function computeFunctionArtifactHash(
+  fn:
+    | FunctionArtifact
+    | (Pick<FunctionArtifact, 'bytecode'> & { functionMetadataHash: Fr; selector: FunctionSelector }),
+) {
+  const selector = 'selector' in fn ? fn.selector : await FunctionSelector.fromNameAndParameters(fn);
+
+  const bytecodeHash = sha256Fr(fn.bytecode).toBuffer();
+  const metadataHash = 'functionMetadataHash' in fn ? fn.functionMetadataHash : computeFunctionMetadataHash(fn);
+  return sha256Fr(Buffer.concat([numToUInt8(VERSION), selector.toBuffer(), metadataHash.toBuffer(), bytecodeHash]));
+}
+
+export function computeFunctionMetadataHash(fn: FunctionArtifact) {
+  return sha256Fr(Buffer.from(JSON.stringify(fn.returnTypes), 'utf8'));
+}
+
+function getLogger() {
+  return createLogger('circuits:artifact_hash');
+}
+
+export function getArtifactMerkleTreeHasher() {
+  return (l: Buffer, r: Buffer) => Promise.resolve(sha256Fr(Buffer.concat([l, r])).toBuffer());
+}

package/src/contract/complete_address.ts

@@ -0,0 +1,155 @@
+import { Fr } from '@aztec/foundation/fields';
+import { hexSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex } from '@aztec/foundation/string';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import { computeAddress, computePreaddress, deriveKeys } from '../keys/index.js';
+import { PublicKeys } from '../keys/public_keys.js';
+import { computePartialAddress } from './contract_address.js';
+import type { PartialAddress } from './partial_address.js';
+
+/**
+ * A complete address is a combination of an Aztec address, a public key and a partial address.
+ *
+ * @remarks We have introduced this type because it is common that these 3 values are used together. They are commonly
+ *          used together because it is the information needed to send user a note.
+ * @remarks See the link below for details about how address is computed:
+ *          https://github.com/AztecProtocol/aztec-packages/blob/master/docs/docs/concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys
+ */
+export class CompleteAddress {
+  private constructor(
+    /** Contract address (typically of an account contract) */
+    public address: AztecAddress,
+    /** User public keys */
+    public publicKeys: PublicKeys,
+    /** Partial key corresponding to the public key to the address. */
+    public partialAddress: PartialAddress,
+  ) {}
+
+  static async create(
+    address: AztecAddress,
+    publicKeys: PublicKeys,
+    partialAddress: PartialAddress,
+  ): Promise<CompleteAddress> {
+    const completeAddress = new CompleteAddress(address, publicKeys, partialAddress);
+    await completeAddress.validate();
+    return completeAddress;
+  }
+
+  /** Size in bytes of an instance */
+  static readonly SIZE_IN_BYTES = 32 * 10;
+
+  static get schema() {
+    return hexSchemaFor(CompleteAddress);
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static async random(): Promise<CompleteAddress> {
+    return await this.fromSecretKeyAndPartialAddress(Fr.random(), Fr.random());
+  }
+
+  static async fromSecretKeyAndPartialAddress(secretKey: Fr, partialAddress: Fr): Promise<CompleteAddress> {
+    const { publicKeys } = await deriveKeys(secretKey);
+    const address = await computeAddress(publicKeys, partialAddress);
+
+    return new CompleteAddress(address, publicKeys, partialAddress);
+  }
+
+  async getPreaddress() {
+    return computePreaddress(await this.publicKeys.hash(), this.partialAddress);
+  }
+
+  static async fromSecretKeyAndInstance(
+    secretKey: Fr,
+    instance: Parameters<typeof computePartialAddress>[0],
+  ): Promise<CompleteAddress> {
+    const partialAddress = await computePartialAddress(instance);
+    return CompleteAddress.fromSecretKeyAndPartialAddress(secretKey, partialAddress);
+  }
+
+  /** Throws if the address is not correctly derived from the public key and partial address.*/
+  public async validate() {
+    const expectedAddress = await computeAddress(this.publicKeys, this.partialAddress);
+
+    if (!expectedAddress.equals(this.address)) {
+      throw new Error(
+        `Address cannot be derived from public keys and partial address (received ${this.address.toString()}, derived ${expectedAddress.toString()})`,
+      );
+    }
+  }
+
+  /**
+   * Gets a readable string representation of the complete address.
+   * @returns A readable string representation of the complete address.
+   */
+  public toReadableString(): string {
+    return `Address: ${this.address.toString()}\nMaster Nullifier Public Key: ${this.publicKeys.masterNullifierPublicKey.toString()}\nMaster Incoming Viewing Public Key: ${this.publicKeys.masterIncomingViewingPublicKey.toString()}\nMaster Outgoing Viewing Public Key: ${this.publicKeys.masterOutgoingViewingPublicKey.toString()}\nMaster Tagging Public Key: ${this.publicKeys.masterTaggingPublicKey.toString()}\nPartial Address: ${this.partialAddress.toString()}\n`;
+  }
+
+  /**
+   * Determines if this CompleteAddress instance is equal to the given CompleteAddress instance.
+   * Equality is based on the content of their respective buffers.
+   *
+   * @param other - The CompleteAddress instance to compare against.
+   * @returns True if the buffers of both instances are equal, false otherwise.
+   */
+  equals(other: CompleteAddress): boolean {
+    return (
+      this.address.equals(other.address) &&
+      this.publicKeys.equals(other.publicKeys) &&
+      this.partialAddress.equals(other.partialAddress)
+    );
+  }
+
+  /**
+   * Converts the CompleteAddress instance into a Buffer.
+   * This method should be used when encoding the address for storage, transmission or serialization purposes.
+   *
+   * @returns A Buffer representation of the CompleteAddress instance.
+   */
+  toBuffer(): Buffer {
+    return serializeToBuffer([this.address, this.publicKeys, this.partialAddress]);
+  }
+
+  /**
+   * Creates an CompleteAddress instance from a given buffer or BufferReader.
+   * If the input is a Buffer, it wraps it in a BufferReader before processing.
+   * Throws an error if the input length is not equal to the expected size.
+   *
+   * @param buffer - The input buffer or BufferReader containing the address data.
+   * @returns - A new CompleteAddress instance with the extracted address data.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): Promise<CompleteAddress> {
+    const reader = BufferReader.asReader(buffer);
+    const address = reader.readObject(AztecAddress);
+    const publicKeys = reader.readObject(PublicKeys);
+    const partialAddress = reader.readObject(Fr);
+    return CompleteAddress.create(address, publicKeys, partialAddress);
+  }
+
+  /**
+   * Create a CompleteAddress instance from a hex-encoded string.
+   * The input 'address' should be prefixed with '0x' or not, and have exactly 128 hex characters representing the x and y coordinates.
+   * Throws an error if the input length is invalid or coordinate values are out of range.
+   *
+   * @param address - The hex-encoded string representing the complete address.
+   * @returns A Point instance.
+   */
+  static fromString(address: string): Promise<CompleteAddress> {
+    return CompleteAddress.fromBuffer(Buffer.from(address.replace(/^0x/i, ''), 'hex'));
+  }
+
+  /**
+   * Convert the CompleteAddress to a hexadecimal string representation, with a "0x" prefix.
+   * The resulting string will have a length of 66 characters (including the prefix).
+   *
+   * @returns A hexadecimal string representation of the CompleteAddress.
+   */
+  toString(): string {
+    return bufferToHex(this.toBuffer());
+  }
+}