@proto-kit/protocol 0.1.1-develop.0

package/src/settlement/contracts/SettlementContractProtocolModule.ts

@@ -0,0 +1,108 @@
+import { inject, injectable, injectAll } from "tsyringe";
+import {
+  ArtifactRecord,
+  ChildVerificationKeyService,
+  CompileRegistry,
+  log,
+} from "@proto-kit/common";
+
+import { BlockProvable } from "../../prover/block/BlockProvable";
+import {
+  ContractModule,
+  SmartContractClassFromInterface,
+} from "../ContractModule";
+import { ProvableSettlementHook } from "../modularity/ProvableSettlementHook";
+
+import { DispatchSmartContractBase } from "./DispatchSmartContract";
+import {
+  SettlementContractType,
+  SettlementSmartContract,
+  SettlementSmartContractBase,
+} from "./SettlementSmartContract";
+import { BridgeContractBase } from "./BridgeContract";
+import { DispatchContractProtocolModule } from "./DispatchContractProtocolModule";
+import { BridgeContractProtocolModule } from "./BridgeContractProtocolModule";
+
+export type SettlementContractConfig = {
+  escapeHatchSlotsInterval?: number;
+};
+
+// 24 hours
+const DEFAULT_ESCAPE_HATCH = (60 / 3) * 24;
+
+@injectable()
+export class SettlementContractProtocolModule extends ContractModule<
+  SettlementContractType,
+  SettlementContractConfig
+> {
+  public constructor(
+    @injectAll("ProvableSettlementHook")
+    private readonly hooks: ProvableSettlementHook<unknown>[],
+    @inject("BlockProver")
+    private readonly blockProver: BlockProvable,
+    @inject("DispatchContract")
+    private readonly dispatchContractModule: DispatchContractProtocolModule,
+    @inject("BridgeContract")
+    private readonly bridgeContractModule: BridgeContractProtocolModule,
+    private readonly childVerificationKeyService: ChildVerificationKeyService
+  ) {
+    super();
+  }
+
+  public contractFactory(): SmartContractClassFromInterface<SettlementContractType> {
+    const { hooks, config } = this;
+    const dispatchContract = this.dispatchContractModule.contractFactory();
+    const bridgeContract = this.bridgeContractModule.contractFactory();
+
+    const escapeHatchSlotsInterval =
+      config.escapeHatchSlotsInterval ?? DEFAULT_ESCAPE_HATCH;
+
+    const { args } = SettlementSmartContractBase;
+    SettlementSmartContractBase.args = {
+      DispatchContract: dispatchContract,
+      hooks,
+      escapeHatchSlotsInterval,
+      BridgeContract: bridgeContract,
+      BridgeContractVerificationKey: args?.BridgeContractVerificationKey,
+      BridgeContractPermissions: args?.BridgeContractPermissions,
+      signedSettlements: args?.signedSettlements,
+      ChildVerificationKeyService: this.childVerificationKeyService,
+    };
+
+    // Ideally we don't want to have this cyclic dependency, but we have it in the protocol,
+    // So its logical that we can't avoid that here
+    BridgeContractBase.args.SettlementContract = SettlementSmartContract;
+
+    DispatchSmartContractBase.args.settlementContractClass =
+      SettlementSmartContract;
+
+    return SettlementSmartContract;
+  }
+
+  public async compile(
+    registry: CompileRegistry
+  ): Promise<ArtifactRecord | undefined> {
+    // Dependencies
+    const bridgeArtifact = await this.bridgeContractModule.compile(registry);
+
+    await this.blockProver.compile(registry);
+
+    // Init params
+    SettlementSmartContractBase.args.BridgeContractVerificationKey =
+      bridgeArtifact.BridgeContract.verificationKey;
+
+    if (SettlementSmartContractBase.args.signedSettlements === undefined) {
+      throw new Error(
+        "Args not fully initialized - make sure to also include the SettlementModule in the sequencer"
+      );
+    }
+
+    log.debug("Compiling Settlement Contract");
+
+    const artifact = await registry.compile(SettlementSmartContract);
+
+    return {
+      SettlementSmartContract: artifact,
+    };
+  }
+}

package/src/settlement/contracts/SettlementSmartContract.ts

@@ -0,0 +1,498 @@
+import {
+  prefixToField,
+  RollupMerkleTree,
+  TypedClass,
+  mapSequential,
+  ChildVerificationKeyService,
+} from "@proto-kit/common";
+import {
+  AccountUpdate,
+  Bool,
+  Field,
+  method,
+  PublicKey,
+  Signature,
+  SmartContract,
+  State,
+  state,
+  UInt32,
+  AccountUpdateForest,
+  TokenContractV2,
+  PrivateKey,
+  VerificationKey,
+  Permissions,
+  Struct,
+  Provable,
+  TokenId,
+  DynamicProof,
+} from "o1js";
+
+import { NetworkState } from "../../model/network/NetworkState";
+import { BlockHashMerkleTree } from "../../prover/block/accummulators/BlockHashMerkleTree";
+import {
+  BlockProverPublicInput,
+  BlockProverPublicOutput,
+} from "../../prover/block/BlockProvable";
+import {
+  ProvableSettlementHook,
+  SettlementHookInputs,
+  SettlementStateRecord,
+} from "../modularity/ProvableSettlementHook";
+
+import { DispatchContractType } from "./DispatchSmartContract";
+import { BridgeContractType } from "./BridgeContract";
+import { TokenBridgeDeploymentAuth } from "./authorizations/TokenBridgeDeploymentAuth";
+import { UpdateMessagesHashAuth } from "./authorizations/UpdateMessagesHashAuth";
+
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+
+export class DynamicBlockProof extends DynamicProof<
+  BlockProverPublicInput,
+  BlockProverPublicOutput
+> {
+  public static publicInputType = BlockProverPublicInput;
+
+  public static publicOutputType = BlockProverPublicOutput;
+
+  public static maxProofsVerified = 2 as const;
+}
+
+export class TokenMapping extends Struct({
+  tokenId: Field,
+  publicKey: PublicKey,
+}) {}
+
+export interface SettlementContractType {
+  authorizationField: State<Field>;
+
+  initialize: (
+    sequencer: PublicKey,
+    dispatchContract: PublicKey,
+    bridgeContract: PublicKey,
+    contractKey: PrivateKey
+  ) => Promise<void>;
+  assertStateRoot: (root: Field) => AccountUpdate;
+  settle: (
+    blockProof: DynamicBlockProof,
+    signature: Signature,
+    dispatchContractAddress: PublicKey,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ) => Promise<void>;
+  addTokenBridge: (
+    tokenId: Field,
+    address: PublicKey,
+    dispatchContract: PublicKey
+  ) => Promise<void>;
+}
+
+// Some random prefix for the sequencer signature
+export const BATCH_SIGNATURE_PREFIX = prefixToField("pk-batchSignature");
+
+// @singleton()
+// export class SettlementSmartContractStaticArgs {
+//   public args?: {
+//     DispatchContract: TypedClass<DispatchContractType & SmartContract>;
+//     hooks: ProvableSettlementHook<unknown>[];
+//     escapeHatchSlotsInterval: number;
+//     BridgeContract: TypedClass<BridgeContractType> & typeof SmartContract;
+//     // Lazily initialized
+//     BridgeContractVerificationKey: VerificationKey | undefined;
+//     BridgeContractPermissions: Permissions | undefined;
+//     signedSettlements: boolean | undefined;
+//   };
+// }
+
+export abstract class SettlementSmartContractBase extends TokenContractV2 {
+  // This pattern of injecting args into a smartcontract is currently the only
+  // viable solution that works given the inheritance issues of o1js
+  // public static args = container.resolve(SettlementSmartContractStaticArgs);
+  public static args: {
+    DispatchContract: TypedClass<DispatchContractType & SmartContract>;
+    hooks: ProvableSettlementHook<unknown>[];
+    escapeHatchSlotsInterval: number;
+    BridgeContract: TypedClass<BridgeContractType> & typeof SmartContract;
+    // Lazily initialized
+    BridgeContractVerificationKey: VerificationKey | undefined;
+    BridgeContractPermissions: Permissions | undefined;
+    signedSettlements: boolean | undefined;
+    ChildVerificationKeyService: ChildVerificationKeyService;
+  };
+
+  events = {
+    "token-bridge-deployed": TokenMapping,
+  };
+
+  abstract sequencerKey: State<Field>;
+  abstract lastSettlementL1BlockHeight: State<UInt32>;
+  abstract stateRoot: State<Field>;
+  abstract networkStateHash: State<Field>;
+  abstract blockHashRoot: State<Field>;
+  abstract dispatchContractAddressX: State<Field>;
+
+  abstract authorizationField: State<Field>;
+
+  // Not @state
+  // abstract offchainStateCommitmentsHash: State<Field>;
+
+  public assertStateRoot(root: Field): AccountUpdate {
+    this.stateRoot.requireEquals(root);
+    return this.self;
+  }
+
+  // TODO Like these properties, I am too lazy to properly infer the types here
+  private assertLazyConfigsInitialized() {
+    const uninitializedProperties: string[] = [];
+    const { args } = SettlementSmartContractBase;
+    if (args.BridgeContractPermissions === undefined) {
+      uninitializedProperties.push("BridgeContractPermissions");
+    }
+    if (args.signedSettlements === undefined) {
+      uninitializedProperties.push("signedSettlements");
+    }
+    if (uninitializedProperties.length > 0) {
+      throw new Error(
+        `Lazy configs of SettlementSmartContract haven't been initialized ${uninitializedProperties.reduce(
+          (a, b) => `${a},${b}`
+        )}`
+      );
+    }
+  }
+
+  protected async deployTokenBridge(
+    tokenId: Field,
+    address: PublicKey,
+    dispatchContractAddress: PublicKey,
+    dispatchContractPreconditionEnforced = false
+  ) {
+    Provable.asProver(() => {
+      this.assertLazyConfigsInitialized();
+    });
+
+    const { args } = SettlementSmartContractBase;
+    const BridgeContractClass = args.BridgeContract;
+    const bridgeContract = new BridgeContractClass(address, tokenId);
+
+    const {
+      BridgeContractVerificationKey,
+      signedSettlements,
+      BridgeContractPermissions,
+    } = args;
+
+    if (
+      signedSettlements === undefined ||
+      BridgeContractPermissions === undefined
+    ) {
+      throw new Error(
+        "Static arguments for SettlementSmartContract not initialized"
+      );
+    }
+
+    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(
+      args.BridgeContractVerificationKey,
+      args.signedSettlements!,
+      args.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,
+      })
+    );
+
+    // We can't set a precondition twice, for the $mina bridge deployment that
+    // would be the case, so we disable it in this case
+    if (!dispatchContractPreconditionEnforced) {
+      this.dispatchContractAddressX.requireEquals(dispatchContractAddress.x);
+    }
+
+    // Set authorization for the auth callback, that we need
+    this.authorizationField.set(
+      new TokenBridgeDeploymentAuth({
+        target: dispatchContractAddress,
+        tokenId,
+        address,
+      }).hash()
+    );
+    const dispatchContract =
+      new SettlementSmartContractBase.args.DispatchContract(
+        dispatchContractAddress
+      );
+    await dispatchContract.enableTokenDeposits(tokenId, address, this.address);
+  }
+
+  protected async initializeBase(
+    sequencer: PublicKey,
+    dispatchContract: PublicKey,
+    bridgeContract: PublicKey,
+    contractKey: PrivateKey
+  ) {
+    this.sequencerKey.getAndRequireEquals().assertEquals(Field(0));
+    this.stateRoot.getAndRequireEquals().assertEquals(Field(0));
+    this.blockHashRoot.getAndRequireEquals().assertEquals(Field(0));
+    this.networkStateHash.getAndRequireEquals().assertEquals(Field(0));
+    this.dispatchContractAddressX.getAndRequireEquals().assertEquals(Field(0));
+
+    this.sequencerKey.set(sequencer.x);
+    this.stateRoot.set(Field(RollupMerkleTree.EMPTY_ROOT));
+    this.blockHashRoot.set(Field(BlockHashMerkleTree.EMPTY_ROOT));
+    this.networkStateHash.set(NetworkState.empty().hash());
+    this.dispatchContractAddressX.set(dispatchContract.x);
+
+    const { DispatchContract } = SettlementSmartContractBase.args;
+    const contractInstance = new DispatchContract(dispatchContract);
+    await contractInstance.initialize(this.address);
+
+    // Deploy bridge contract for $Mina
+    await this.deployTokenBridge(
+      this.tokenId,
+      bridgeContract,
+      dispatchContract,
+      true
+    );
+
+    contractKey.toPublicKey().assertEquals(this.address);
+  }
+
+  protected async settleBase(
+    blockProof: DynamicBlockProof,
+    signature: Signature,
+    dispatchContractAddress: PublicKey,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ) {
+    // Brought in as a constant
+    const blockProofVk =
+      SettlementSmartContractBase.args.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();
+    const onChainDispatchContractAddressX =
+      this.dispatchContractAddressX.getAndRequireEquals();
+
+    onChainDispatchContractAddressX.assertEquals(
+      dispatchContractAddress.x,
+      "DispatchContract address not provided correctly"
+    );
+
+    const { DispatchContract, escapeHatchSlotsInterval, hooks } =
+      SettlementSmartContractBase.args;
+
+    // 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();
+
+    // 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"
+      );
+
+    blockProof.publicOutput.closed.assertEquals(
+      Bool(true),
+      "Supplied proof is not a closed BlockProof"
+    );
+
+    // 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);
+
+    // 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
+    );
+
+    this.lastSettlementL1BlockHeight.set(minBlockHeightIncluded);
+  }
+}
+
+export class SettlementSmartContract
+  extends SettlementSmartContractBase
+  implements SettlementContractType
+{
+  @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(Field) public dispatchContractAddressX = State<Field>();
+
+  @state(Field) public authorizationField = State<Field>();
+
+  @method async approveBase(forest: AccountUpdateForest) {
+    this.checkZeroBalanceChange(forest);
+  }
+
+  @method
+  public async initialize(
+    sequencer: PublicKey,
+    dispatchContract: PublicKey,
+    bridgeContract: PublicKey,
+    contractKey: PrivateKey
+  ) {
+    await this.initializeBase(
+      sequencer,
+      dispatchContract,
+      bridgeContract,
+      contractKey
+    );
+  }
+
+  @method
+  public async addTokenBridge(
+    tokenId: Field,
+    address: PublicKey,
+    dispatchContract: PublicKey
+  ) {
+    await this.deployTokenBridge(tokenId, address, dispatchContract);
+  }
+
+  @method
+  public async settle(
+    blockProof: DynamicBlockProof,
+    signature: Signature,
+    dispatchContractAddress: PublicKey,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ) {
+    return await this.settleBase(
+      blockProof,
+      signature,
+      dispatchContractAddress,
+      publicKey,
+      inputNetworkState,
+      outputNetworkState,
+      newPromisedMessagesHash
+    );
+  }
+}
+
+/* eslint-enable @typescript-eslint/lines-between-class-members */

package/src/settlement/contracts/TokenBridgeTree.ts

@@ -0,0 +1,73 @@
+import {
+  createMerkleTree,
+  InMemoryMerkleTreeStorage,
+  log,
+} from "@proto-kit/common";
+import { Field, Poseidon, PublicKey, SmartContract, Struct } from "o1js";
+
+/**
+ * Merkle tree that contains all the deployed token bridges as a mapping of
+ * tokenId => PublicKey
+ *
+ * It should be used as an append-only tree with incremental indizes - this allows
+ * us to reduce the height of it
+ */
+export class TokenBridgeTree extends createMerkleTree(256) {
+  public indizes: Record<string, bigint> = {};
+
+  /**
+   * Initializes and fills the tree based on all on-chain events that have been
+   * emitted by every emit
+   */
+  public static async buildTreeFromEvents(
+    contract: SmartContract & {
+      events: { "token-bridge-added": typeof TokenBridgeTreeAddition };
+    }
+  ) {
+    const events = await contract.fetchEvents();
+
+    log.debug(`Found ${events.length} token bridge add events`);
+
+    const tree = new TokenBridgeTree(new InMemoryMerkleTreeStorage());
+    const indizes: Record<string, bigint> = {};
+
+    events.forEach(({ type, event }) => {
+      if (type === "token-bridge-added") {
+        const addition =
+          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+          event.data as unknown as TokenBridgeTreeAddition;
+
+        tree.setLeaf(addition.index.toBigInt(), addition.value.hash());
+
+        indizes[addition.value.tokenId.toString()] = addition.index.toBigInt();
+      }
+    });
+    tree.indizes = indizes;
+    return tree;
+  }
+
+  public getIndex(tokenId: Field): bigint {
+    return this.indizes[tokenId.toString()];
+  }
+}
+
+export class TokenBridgeTreeWitness extends TokenBridgeTree.WITNESS {}
+
+export class TokenBridgeEntry extends Struct({
+  address: PublicKey,
+  tokenId: Field,
+}) {
+  public hash() {
+    return Poseidon.hash(TokenBridgeEntry.toFields(this));
+  }
+}
+
+export class TokenBridgeAttestation extends Struct({
+  witness: TokenBridgeTreeWitness,
+  index: Field,
+}) {}
+
+export class TokenBridgeTreeAddition extends Struct({
+  index: Field,
+  value: TokenBridgeEntry,
+}) {}

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));
+  }
+}