@proto-kit/protocol 0.1.1-develop.191 → 0.1.1-develop.2024

package/src/settlement/contracts/authorizations/ContractAuthorization.ts

@@ -0,0 +1,11 @@
+import { Field, PublicKey } from "o1js";
+
+/**
+ * Interface for cross-contract call authorization
+ * See https://github.com/proto-kit/framework/issues/202#issuecomment-2407263173
+ */
+export interface ContractAuthorization {
+  target: PublicKey;
+
+  hash: () => Field;
+}

package/src/settlement/contracts/authorizations/TokenBridgeDeploymentAuth.ts

@@ -0,0 +1,16 @@
+import { Field, Poseidon, PublicKey, Struct } from "o1js";
+
+import { ContractAuthorization } from "./ContractAuthorization";
+
+export class TokenBridgeDeploymentAuth
+  extends Struct({
+    target: PublicKey,
+    tokenId: Field,
+    address: PublicKey,
+  })
+  implements ContractAuthorization
+{
+  public hash() {
+    return Poseidon.hash(TokenBridgeDeploymentAuth.toFields(this));
+  }
+}

package/src/settlement/contracts/authorizations/UpdateMessagesHashAuth.ts

@@ -0,0 +1,16 @@
+import { Field, Poseidon, PublicKey, Struct } from "o1js";
+
+import { ContractAuthorization } from "./ContractAuthorization";
+
+export class UpdateMessagesHashAuth
+  extends Struct({
+    target: PublicKey,
+    executedMessagesHash: Field,
+    newPromisedMessagesHash: Field,
+  })
+  implements ContractAuthorization
+{
+  public hash() {
+    return Poseidon.hash(UpdateMessagesHashAuth.toFields(this));
+  }
+}

package/src/settlement/contracts/settlement/BridgingSettlementContract.ts

@@ -0,0 +1,283 @@
+import { TypedClass, O1PublicKeyOption } from "@proto-kit/common";
+import {
+  AccountUpdate,
+  Bool,
+  Field,
+  method,
+  PublicKey,
+  Signature,
+  SmartContract,
+  State,
+  state,
+  UInt32,
+  AccountUpdateForest,
+  VerificationKey,
+  Permissions,
+  Struct,
+  TokenId,
+  DeployArgs,
+} from "o1js";
+import { container } from "tsyringe";
+
+import { NetworkState } from "../../../model/network/NetworkState";
+import { DispatchContractType } from "../DispatchSmartContract";
+import { BridgeContractType } from "../BridgeContract";
+import { TokenBridgeDeploymentAuth } from "../authorizations/TokenBridgeDeploymentAuth";
+import { UpdateMessagesHashAuth } from "../authorizations/UpdateMessagesHashAuth";
+import {
+  ContractArgsRegistry,
+  NaiveObjectSchema,
+  StaticInitializationContract,
+} from "../../ContractArgsRegistry";
+
+import {
+  DynamicBlockProof,
+  SettlementBase,
+  SettlementContractArgs,
+  SettlementContractArgsSchema,
+  SettlementContractType,
+} from "./SettlementBase";
+
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+
+export class TokenMapping extends Struct({
+  tokenId: Field,
+  publicKey: PublicKey,
+}) {}
+
+export interface BridgingSettlementContractType extends SettlementContractType {
+  authorizationField: State<Field>;
+
+  assertStateRoot: (root: Field) => AccountUpdate;
+  addTokenBridge: (tokenId: Field, address: PublicKey) => Promise<void>;
+}
+
+export interface BridgingSettlementContractArgs extends SettlementContractArgs {
+  DispatchContract: TypedClass<DispatchContractType & SmartContract>;
+  BridgeContract: TypedClass<BridgeContractType> & typeof SmartContract;
+  // Lazily initialized
+  BridgeContractVerificationKey: VerificationKey | undefined;
+  BridgeContractPermissions: Permissions;
+}
+
+export const BridgingSettlementContractArgsSchema: NaiveObjectSchema<BridgingSettlementContractArgs> =
+  {
+    ...SettlementContractArgsSchema,
+    DispatchContract: "Required",
+    BridgeContract: "Required",
+    BridgeContractVerificationKey: "Optional",
+    BridgeContractPermissions: "Required",
+  };
+
+export abstract class BridgingSettlementContractBase
+  extends SettlementBase
+  implements StaticInitializationContract<BridgingSettlementContractArgs>
+{
+  public getInitializationArgs(): BridgingSettlementContractArgs {
+    return container
+      .resolve(ContractArgsRegistry)
+      .getArgs("SettlementContract", BridgingSettlementContractArgsSchema);
+  }
+
+  events = {
+    "token-bridge-deployed": TokenMapping,
+  };
+
+  abstract dispatchContractAddress: State<PublicKey>;
+
+  abstract authorizationField: State<Field>;
+
+  // Not @state
+  // abstract offchainStateCommitmentsHash: State<Field>;
+
+  public assertStateRoot(root: Field): AccountUpdate {
+    this.stateRoot.requireEquals(root);
+    return this.self;
+  }
+
+  protected async initializeBaseBridging(
+    sequencer: PublicKey,
+    dispatchContract: PublicKey
+  ) {
+    await super.initializeBase(sequencer);
+
+    this.dispatchContractAddress.set(dispatchContract);
+  }
+
+  // TODO We should move this to the dispatchcontract eventually - or after mesa
+  //  to the combined settlement & dispatch contract
+  protected async deployTokenBridge(tokenId: Field, address: PublicKey) {
+    const {
+      BridgeContractVerificationKey,
+      signedSettlements,
+      BridgeContractPermissions,
+      BridgeContract: BridgeContractClass,
+      DispatchContract,
+    } = this.getInitializationArgs();
+
+    const bridgeContract = new BridgeContractClass(address, tokenId);
+
+    if (
+      BridgeContractVerificationKey !== undefined &&
+      !BridgeContractVerificationKey.hash.isConstant()
+    ) {
+      throw new Error("Bridge contract verification key has to be constants");
+    }
+
+    // This function is not a zkapps method, therefore it will be part of this methods execution
+    // The returning account update (owner.self) is therefore part of this circuit and is assertable
+    const deploymentAccountUpdate = await bridgeContract.deployProvable(
+      BridgeContractVerificationKey,
+      signedSettlements!,
+      BridgeContractPermissions!,
+      this.address
+    );
+
+    this.approve(deploymentAccountUpdate);
+
+    this.self.body.mayUseToken = {
+      // Only set this if we deploy a custom token
+      parentsOwnToken: tokenId.equals(TokenId.default).not(),
+      inheritFromParent: Bool(false),
+    };
+
+    this.emitEvent(
+      "token-bridge-deployed",
+      new TokenMapping({
+        tokenId: tokenId,
+        publicKey: address,
+      })
+    );
+
+    const dispatchContractAddress =
+      this.dispatchContractAddress.getAndRequireEquals();
+
+    // Set authorization for the auth callback, that we need
+    this.authorizationField.set(
+      new TokenBridgeDeploymentAuth({
+        target: dispatchContractAddress,
+        tokenId,
+        address,
+      }).hash()
+    );
+    const dispatchContract = new DispatchContract(dispatchContractAddress);
+    await dispatchContract.enableTokenDeposits(tokenId, address, this.address);
+  }
+
+  protected async settleBaseBridging(
+    blockProof: DynamicBlockProof,
+    signature: Signature,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ) {
+    await super.settleBase(
+      blockProof,
+      signature,
+      publicKey,
+      inputNetworkState,
+      outputNetworkState,
+      newPromisedMessagesHash
+    );
+
+    const dispatchContractAddress =
+      this.dispatchContractAddress.getAndRequireEquals();
+
+    const { DispatchContract } = this.getInitializationArgs();
+
+    // Get dispatch contract values
+    // These values are witnesses but will be checked later on the AU
+    // call to the dispatch contract via .updateMessagesHash()
+    const dispatchContract = new DispatchContract(dispatchContractAddress);
+    const promisedMessagesHash = dispatchContract.promisedMessagesHash.get();
+
+    // Assert and apply deposit commitments
+    promisedMessagesHash.assertEquals(
+      blockProof.publicOutput.incomingMessagesHash,
+      "Promised messages not honored"
+    );
+
+    // Set authorization for the dispatchContract to verify the messages hash update
+    this.authorizationField.set(
+      new UpdateMessagesHashAuth({
+        target: dispatchContract.address,
+        executedMessagesHash: promisedMessagesHash,
+        newPromisedMessagesHash,
+      }).hash()
+    );
+
+    // Call DispatchContract
+    // This call checks that the promisedMessagesHash, which is already proven
+    // to be the blockProofs publicoutput, is actually the current on-chain
+    // promisedMessageHash. It also checks the newPromisedMessagesHash to be
+    // a current sequencestate value
+    await dispatchContract.updateMessagesHash(
+      promisedMessagesHash,
+      newPromisedMessagesHash
+    );
+  }
+}
+
+export class BridgingSettlementContract
+  extends BridgingSettlementContractBase
+  implements BridgingSettlementContractType
+{
+  @state(Field) public sequencerKey = State<Field>();
+  @state(UInt32) public lastSettlementL1BlockHeight = State<UInt32>();
+
+  @state(Field) public stateRoot = State<Field>();
+  @state(Field) public networkStateHash = State<Field>();
+  @state(Field) public blockHashRoot = State<Field>();
+
+  @state(PublicKey) public dispatchContractAddress = State<PublicKey>();
+
+  @state(Field) public authorizationField = State<Field>();
+
+  public async deployAndInitialize(
+    args: DeployArgs | undefined,
+    permissions: Permissions,
+    sequencer: PublicKey,
+    dispatchContract: O1PublicKeyOption
+  ): Promise<void> {
+    dispatchContract.assertSome(
+      "Bridging-enabled settlement contract requires a dispatch contract address"
+    );
+
+    await super.deploy(args);
+
+    this.self.account.permissions.set(permissions);
+
+    await this.initializeBaseBridging(sequencer, dispatchContract.value);
+  }
+
+  @method async approveBase(forest: AccountUpdateForest) {
+    this.checkZeroBalanceChange(forest);
+  }
+
+  @method
+  public async addTokenBridge(tokenId: Field, address: PublicKey) {
+    await this.deployTokenBridge(tokenId, address);
+  }
+
+  @method
+  public async settle(
+    blockProof: DynamicBlockProof,
+    signature: Signature,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ) {
+    return await this.settleBaseBridging(
+      blockProof,
+      signature,
+      publicKey,
+      inputNetworkState,
+      outputNetworkState,
+      newPromisedMessagesHash
+    );
+  }
+}
+
+/* eslint-enable @typescript-eslint/lines-between-class-members */

package/src/settlement/contracts/settlement/SettlementBase.ts

@@ -0,0 +1,249 @@
+import {
+  DeployArgs,
+  DynamicProof,
+  Field,
+  Option,
+  PublicKey,
+  Signature,
+  State,
+  TokenContract,
+  UInt32,
+  Permissions,
+} from "o1js";
+import {
+  ChildVerificationKeyService,
+  LinkedMerkleTree,
+  mapSequential,
+  prefixToField,
+} from "@proto-kit/common";
+import { container } from "tsyringe";
+
+import { BlockHashMerkleTree } from "../../../prover/block/accummulators/BlockHashMerkleTree";
+import { NetworkState } from "../../../model/network/NetworkState";
+import {
+  ProvableSettlementHook,
+  SettlementHookInputs,
+  SettlementStateRecord,
+} from "../../modularity/ProvableSettlementHook";
+import {
+  BlockProverPublicInput,
+  BlockProverPublicOutput,
+} from "../../../prover/block/BlockProvable";
+import {
+  ContractArgsRegistry,
+  NaiveObjectSchema,
+  StaticInitializationContract,
+} from "../../ContractArgsRegistry";
+
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+
+// Some random prefix for the sequencer signature
+export const BATCH_SIGNATURE_PREFIX = prefixToField("pk-batchSignature");
+
+export class DynamicBlockProof extends DynamicProof<
+  BlockProverPublicInput,
+  BlockProverPublicOutput
+> {
+  public static publicInputType = BlockProverPublicInput;
+
+  public static publicOutputType = BlockProverPublicOutput;
+
+  public static maxProofsVerified = 2 as const;
+}
+
+export interface SettlementContractType {
+  sequencerKey: State<Field>;
+  lastSettlementL1BlockHeight: State<UInt32>;
+  stateRoot: State<Field>;
+  networkStateHash: State<Field>;
+  blockHashRoot: State<Field>;
+
+  deployAndInitialize: (
+    args: DeployArgs | undefined,
+    permissions: Permissions,
+    sequencer: PublicKey,
+    dispatchContract: Option<PublicKey>
+  ) => Promise<void>;
+
+  settle: (
+    blockProof: DynamicBlockProof,
+    signature: Signature,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ) => Promise<void>;
+}
+
+export interface SettlementContractArgs {
+  hooks: ProvableSettlementHook<unknown>[];
+  escapeHatchSlotsInterval: number;
+  signedSettlements: boolean;
+  ChildVerificationKeyService: ChildVerificationKeyService;
+}
+
+export const SettlementContractArgsSchema: NaiveObjectSchema<SettlementContractArgs> =
+  {
+    ChildVerificationKeyService: "Required",
+    hooks: "Required",
+    escapeHatchSlotsInterval: "Required",
+    signedSettlements: "Required",
+  };
+
+export abstract class SettlementBase
+  extends TokenContract
+  implements StaticInitializationContract<SettlementContractArgs>
+{
+  getInitializationArgs(): SettlementContractArgs {
+    return container
+      .resolve(ContractArgsRegistry)
+      .getArgs("SettlementContract", SettlementContractArgsSchema);
+  }
+
+  abstract sequencerKey: State<Field>;
+  abstract lastSettlementL1BlockHeight: State<UInt32>;
+  abstract stateRoot: State<Field>;
+  abstract networkStateHash: State<Field>;
+  abstract blockHashRoot: State<Field>;
+
+  protected async initializeBase(sequencer: PublicKey) {
+    this.sequencerKey.set(sequencer.x);
+    this.stateRoot.set(LinkedMerkleTree.EMPTY_ROOT);
+    this.blockHashRoot.set(Field(BlockHashMerkleTree.EMPTY_ROOT));
+    this.networkStateHash.set(NetworkState.empty().hash());
+  }
+
+  abstract settle(
+    blockProof: DynamicBlockProof,
+    signature: Signature,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ): Promise<void>;
+
+  abstract deployAndInitialize(
+    args: DeployArgs | undefined,
+    permissions: Permissions,
+    sequencer: PublicKey,
+    dispatchContract: Option<PublicKey>
+  ): Promise<void>;
+
+  protected async settleBase(
+    blockProof: DynamicBlockProof,
+    signature: Signature,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ) {
+    const {
+      escapeHatchSlotsInterval,
+      hooks,
+      ChildVerificationKeyService: childVerificationKeyService,
+    } = this.getInitializationArgs();
+
+    // Brought in as a constant
+    const blockProofVk =
+      childVerificationKeyService.getVerificationKey("BlockProver");
+    if (!blockProofVk.hash.isConstant()) {
+      throw new Error("Sanity check - vk hash has to be constant");
+    }
+    // Verify the blockproof
+
+    blockProof.verify(blockProofVk);
+    // Get and assert on-chain values
+    const stateRoot = this.stateRoot.getAndRequireEquals();
+    const networkStateHash = this.networkStateHash.getAndRequireEquals();
+    const blockHashRoot = this.blockHashRoot.getAndRequireEquals();
+    const sequencerKey = this.sequencerKey.getAndRequireEquals();
+
+    const lastSettlementL1BlockHeight =
+      this.lastSettlementL1BlockHeight.getAndRequireEquals();
+
+    // Get block height and use the lower bound for all ops
+    const minBlockHeightIncluded = this.network.blockchainLength.get();
+    this.network.blockchainLength.requireBetween(
+      minBlockHeightIncluded,
+      // 5 because that is the length the newPromisedMessagesHash will be valid
+      minBlockHeightIncluded.add(4)
+    );
+
+    // Check signature/escape catch
+    publicKey.x.assertEquals(
+      sequencerKey,
+      "Sequencer public key witness not matching"
+    );
+    const signatureValid = signature.verify(publicKey, [
+      BATCH_SIGNATURE_PREFIX,
+      lastSettlementL1BlockHeight.value,
+    ]);
+    const escapeHatchActivated = lastSettlementL1BlockHeight
+      .add(UInt32.from(escapeHatchSlotsInterval))
+      .lessThan(minBlockHeightIncluded);
+    signatureValid
+      .or(escapeHatchActivated)
+      .assertTrue(
+        "Sequencer signature not valid and escape hatch not activated"
+      );
+
+    // Assert correctness of networkState witness
+    inputNetworkState
+      .hash()
+      .assertEquals(networkStateHash, "InputNetworkState witness not valid");
+    outputNetworkState
+      .hash()
+      .assertEquals(
+        blockProof.publicOutput.networkStateHash,
+        "OutputNetworkState witness not valid"
+      );
+
+    // Check remainders are zero
+    blockProof.publicOutput.proverStateRemainder.assertEquals(
+      Field(0),
+      "Supplied proof is has outstanding block prover state to be proven"
+    );
+
+    // Execute onSettlementHooks for additional checks
+    const stateRecord: SettlementStateRecord = {
+      blockHashRoot,
+      stateRoot,
+      networkStateHash,
+      lastSettlementL1BlockHeight,
+      sequencerKey: publicKey,
+    };
+    const inputs: SettlementHookInputs = {
+      blockProof,
+      contractState: stateRecord,
+      newPromisedMessagesHash,
+      fromNetworkState: inputNetworkState,
+      toNetworkState: outputNetworkState,
+      currentL1BlockHeight: minBlockHeightIncluded,
+    };
+    await mapSequential(hooks, async (hook) => {
+      await hook.beforeSettlement(this, inputs);
+    });
+
+    // Apply blockProof
+    stateRoot.assertEquals(
+      blockProof.publicInput.stateRoot,
+      "Input state root not matching"
+    );
+
+    networkStateHash.assertEquals(
+      blockProof.publicInput.networkStateHash,
+      "Input networkStateHash not matching"
+    );
+    blockHashRoot.assertEquals(
+      blockProof.publicInput.blockHashRoot,
+      "Input blockHashRoot not matching"
+    );
+    this.stateRoot.set(blockProof.publicOutput.stateRoot);
+    this.networkStateHash.set(blockProof.publicOutput.networkStateHash);
+    this.blockHashRoot.set(blockProof.publicOutput.blockHashRoot);
+
+    this.lastSettlementL1BlockHeight.set(minBlockHeightIncluded);
+  }
+}
+
+/* eslint-enable @typescript-eslint/lines-between-class-members */

package/src/settlement/contracts/settlement/SettlementContract.ts

@@ -0,0 +1,75 @@
+import {
+  State,
+  UInt32,
+  AccountUpdateForest,
+  state,
+  method,
+  PublicKey,
+  Field,
+  Signature,
+  DeployArgs,
+  Permissions,
+} from "o1js";
+import { O1PublicKeyOption } from "@proto-kit/common";
+
+import { NetworkState } from "../../../model/network/NetworkState";
+
+import {
+  DynamicBlockProof,
+  SettlementBase,
+  SettlementContractType,
+} from "./SettlementBase";
+
+export class SettlementContract
+  extends SettlementBase
+  implements SettlementContractType
+{
+  @state(Field) sequencerKey = State<Field>();
+
+  @state(UInt32) lastSettlementL1BlockHeight = State<UInt32>();
+
+  @state(Field) stateRoot = State<Field>();
+
+  @state(Field) networkStateHash = State<Field>();
+
+  @state(Field) blockHashRoot = State<Field>();
+
+  public async deployAndInitialize(
+    args: DeployArgs | undefined,
+    permissions: Permissions,
+    sequencer: PublicKey,
+    dispatchContract: O1PublicKeyOption
+  ): Promise<void> {
+    dispatchContract.assertNone(
+      "Non-bridging settlement contract doesn't require a dispatch contract"
+    );
+
+    await super.deploy(args);
+
+    this.self.account.permissions.set(permissions);
+
+    await this.initializeBase(sequencer);
+  }
+
+  @method async approveBase(forest: AccountUpdateForest) {
+    this.checkZeroBalanceChange(forest);
+  }
+
+  @method async settle(
+    blockProof: DynamicBlockProof,
+    signature: Signature,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ): Promise<void> {
+    await super.settleBase(
+      blockProof,
+      signature,
+      publicKey,
+      inputNetworkState,
+      outputNetworkState,
+      newPromisedMessagesHash
+    );
+  }
+}

package/src/settlement/messages/Deposit.ts

@@ -0,0 +1,7 @@
+import { Field, PublicKey, Struct, UInt64 } from "o1js";
+
+export class Deposit extends Struct({
+  tokenId: Field,
+  address: PublicKey,
+  amount: UInt64,
+}) {}

package/src/settlement/messages/OutgoingMessage.ts

@@ -0,0 +1,17 @@
+import { Field, Struct } from "o1js";
+
+export class OutgoingMessageKeyStruct extends Struct({
+  index: Field,
+  tokenId: Field,
+}) {}
+
+export type OutgoingMessageEvent<T> = {
+  key: OutgoingMessageKeyStruct;
+  value: T;
+  messageType: Field;
+};
+
+export type OutgoingMessage<T> = {
+  value: T;
+  messageType: Field;
+};