@proto-kit/protocol 0.1.1-develop.1086

package/src/settlement/contracts/DispatchContractProtocolModule.ts

@@ -0,0 +1,39 @@
+import { inject, injectable } from "tsyringe";
+
+import { RuntimeLike } from "../../model/RuntimeLike";
+import {
+  ContractModule,
+  SmartContractClassFromInterface,
+} from "../ContractModule";
+
+import {
+  DispatchSmartContract,
+  DispatchContractType,
+} from "./DispatchSmartContract";
+
+export type DispatchContractConfig = {
+  incomingMessagesMethods: Record<string, `${string}.${string}`>;
+};
+
+@injectable()
+export class DispatchContractProtocolModule extends ContractModule<
+  DispatchContractType,
+  undefined,
+  DispatchContractConfig
+> {
+  public constructor(@inject("Runtime") private readonly runtime: RuntimeLike) {
+    super();
+  }
+
+  public contractFactory(): SmartContractClassFromInterface<DispatchContractType> {
+    const { incomingMessagesMethods } = this.config;
+    const methodIdMappings = this.runtime.methodIdResolver.methodIdMap();
+
+    DispatchSmartContract.args = {
+      incomingMessagesPaths: incomingMessagesMethods,
+      methodIdMappings,
+    };
+
+    return DispatchSmartContract;
+  }
+}

package/src/settlement/contracts/DispatchSmartContract.ts

@@ -0,0 +1,136 @@
+import {
+  AccountUpdate,
+  Field,
+  method,
+  Poseidon,
+  ProvableExtended,
+  PublicKey,
+  Reducer,
+  SmartContract,
+  State,
+  state,
+  UInt64,
+} from "o1js";
+
+import { RuntimeMethodIdMapping } from "../../model/RuntimeLike";
+import { RuntimeTransaction } from "../../model/transaction/RuntimeTransaction";
+import {
+  MinaActions,
+  MinaEvents,
+} from "../../utils/MinaPrefixedProvableHashList";
+import { Deposit } from "../messages/Deposit";
+
+export const ACTIONS_EMPTY_HASH = Reducer.initialActionState;
+
+export interface DispatchContractType {
+  updateMessagesHash: (
+    executedMessagesHash: Field,
+    newPromisedMessagesHash: Field
+  ) => Promise<void>;
+  initialize: (settlementContract: PublicKey) => Promise<void>;
+
+  promisedMessagesHash: State<Field>;
+}
+
+export class DispatchSmartContract
+  extends SmartContract
+  implements DispatchContractType
+{
+  public static args: {
+    methodIdMappings: RuntimeMethodIdMapping;
+    incomingMessagesPaths: Record<string, `${string}.${string}`>;
+  };
+
+  @state(Field) public promisedMessagesHash = State<Field>();
+
+  @state(Field) public honoredMessagesHash = State<Field>();
+
+  @state(PublicKey) public settlementContract = State<PublicKey>();
+
+  @method
+  public async updateMessagesHash(
+    executedMessagesHash: Field,
+    newPromisedMessagesHash: Field
+  ) {
+    const promisedMessagesHash =
+      this.promisedMessagesHash.getAndRequireEquals();
+    this.honoredMessagesHash.getAndRequireEquals();
+
+    executedMessagesHash.assertEquals(promisedMessagesHash);
+
+    this.honoredMessagesHash.set(executedMessagesHash);
+
+    // Assert and apply new promisedMessagesHash
+    this.self.account.actionState.requireEquals(newPromisedMessagesHash);
+    this.promisedMessagesHash.set(newPromisedMessagesHash);
+  }
+
+  @method
+  public async initialize(settlementContract: PublicKey) {
+    this.promisedMessagesHash.getAndRequireEquals().assertEquals(Field(0));
+    this.honoredMessagesHash.getAndRequireEquals().assertEquals(Field(0));
+    this.settlementContract
+      .getAndRequireEquals()
+      .assertEquals(PublicKey.empty<typeof PublicKey>());
+
+    this.promisedMessagesHash.set(ACTIONS_EMPTY_HASH);
+    this.honoredMessagesHash.set(ACTIONS_EMPTY_HASH);
+    this.settlementContract.set(settlementContract);
+  }
+
+  private dispatchMessage<Type>(
+    methodId: Field,
+    value: Type,
+    valueType: ProvableExtended<Type>
+  ) {
+    const args = valueType.toFields(value);
+    // Should be the same as RuntimeTransaction.hash
+    const argsHash = Poseidon.hash(args);
+    const runtimeTransaction = RuntimeTransaction.fromMessage({
+      methodId,
+      argsHash,
+    });
+
+    // Append tx to incomingMessagesHash
+    const actionData = runtimeTransaction.hashData();
+    const actionHash = MinaActions.actionHash(actionData);
+
+    this.self.body.actions = {
+      hash: actionHash,
+      data: [actionData],
+    };
+
+    const eventHash = MinaEvents.eventHash(args);
+    this.self.body.events = {
+      hash: eventHash,
+      data: [args],
+    };
+  }
+
+  @method
+  public async deposit(amount: UInt64) {
+    // Save this, since otherwise it would be a second witness later,
+    // which could be a different values than the first
+    const sender = this.sender.getUnconstrained();
+
+    const settlementContract = this.settlementContract.getAndRequireEquals();
+
+    // Credit the amount to the settlement contract
+    const balanceAU = AccountUpdate.create(settlementContract);
+    balanceAU.balance.addInPlace(amount);
+    this.self.approve(balanceAU);
+
+    const action = new Deposit({
+      address: sender,
+      amount,
+    });
+
+    const { methodIdMappings, incomingMessagesPaths } =
+      DispatchSmartContract.args;
+
+    const methodId = Field(
+      methodIdMappings[incomingMessagesPaths.deposit].methodId
+    ).toConstant();
+    this.dispatchMessage(methodId.toConstant(), action, Deposit);
+  }
+}

package/src/settlement/contracts/SettlementContractProtocolModule.ts

@@ -0,0 +1,67 @@
+import { TypedClass } from "@proto-kit/common";
+import { SmartContract } from "o1js";
+import { inject, injectable, injectAll } from "tsyringe";
+
+import { BlockProvable } from "../../prover/block/BlockProvable";
+import {
+  ContractModule,
+  SmartContractClassFromInterface,
+} from "../ContractModule";
+import { ProvableSettlementHook } from "../modularity/ProvableSettlementHook";
+
+import { DispatchContractType } from "./DispatchSmartContract";
+import {
+  LazyBlockProof,
+  SettlementContractType,
+  SettlementSmartContract,
+} from "./SettlementSmartContract";
+
+export type SettlementContractConfig = {
+  escapeHatchSlotsInterval?: number;
+  withdrawalStatePath: `${string}.${string}`;
+  withdrawalMethodPath: `${string}.${string}`;
+};
+
+// 24 hours
+const DEFAULT_ESCAPE_HATCH = (60 / 3) * 24;
+
+@injectable()
+export class SettlementContractProtocolModule extends ContractModule<
+  SettlementContractType,
+  TypedClass<DispatchContractType & SmartContract>,
+  SettlementContractConfig
+> {
+  public constructor(
+    @injectAll("ProvableSettlementHook")
+    private readonly hooks: ProvableSettlementHook<unknown>[],
+    @inject("BlockProver")
+    private readonly blockProver: BlockProvable
+  ) {
+    LazyBlockProof.tag = blockProver.zkProgrammable.zkProgram[0].Proof.tag;
+    super();
+  }
+
+  public contractFactory(
+    dispatchContract: TypedClass<DispatchContractType & SmartContract>
+  ): SmartContractClassFromInterface<SettlementContractType> {
+    const { hooks, config } = this;
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const withdrawalStatePathSplit = config.withdrawalStatePath.split(".") as [
+      string,
+      string,
+    ];
+
+    const escapeHatchSlotsInterval =
+      config.escapeHatchSlotsInterval ?? DEFAULT_ESCAPE_HATCH;
+
+    SettlementSmartContract.args = {
+      DispatchContract: dispatchContract,
+      hooks,
+      withdrawalStatePath: withdrawalStatePathSplit,
+      escapeHatchSlotsInterval,
+    };
+
+    return SettlementSmartContract;
+  }
+}

package/src/settlement/contracts/SettlementSmartContract.ts

@@ -0,0 +1,344 @@
+import {
+  prefixToField,
+  RollupMerkleTree,
+  TypedClass,
+  mapSequential,
+} from "@proto-kit/common";
+import {
+  AccountUpdate,
+  Bool,
+  Field,
+  method,
+  Mina,
+  Poseidon,
+  Proof,
+  Provable,
+  PublicKey,
+  Signature,
+  SmartContract,
+  State,
+  state,
+  TokenId,
+  UInt32,
+  UInt64,
+  TokenContract,
+  AccountUpdateForest,
+} from "o1js";
+
+import { NetworkState } from "../../model/network/NetworkState";
+import { Path } from "../../model/Path";
+import { BlockHashMerkleTree } from "../../prover/block/accummulators/BlockHashMerkleTree";
+import {
+  BlockProverPublicInput,
+  BlockProverPublicOutput,
+} from "../../prover/block/BlockProvable";
+import {
+  OUTGOING_MESSAGE_BATCH_SIZE,
+  OutgoingMessageArgumentBatch,
+} from "../messages/OutgoingMessageArgument";
+import { Withdrawal } from "../messages/Withdrawal";
+import {
+  ProvableSettlementHook,
+  SettlementHookInputs,
+  SettlementStateRecord,
+} from "../modularity/ProvableSettlementHook";
+
+import { DispatchContractType } from "./DispatchSmartContract";
+
+/* eslint-disable @typescript-eslint/lines-between-class-members */
+
+export class LazyBlockProof extends Proof<
+  BlockProverPublicInput,
+  BlockProverPublicOutput
+> {
+  public static publicInputType = BlockProverPublicInput;
+
+  public static publicOutputType = BlockProverPublicOutput;
+
+  public static tag: () => { name: string } = () => {
+    throw new Error("Tag not initialized yet");
+  };
+}
+
+export interface SettlementContractType {
+  initialize: (
+    sequencer: PublicKey,
+    dispatchContract: PublicKey
+  ) => Promise<void>;
+  settle: (
+    blockProof: LazyBlockProof,
+    signature: Signature,
+    dispatchContractAddress: PublicKey,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ) => Promise<void>;
+  rollupOutgoingMessages: (
+    batch: OutgoingMessageArgumentBatch
+  ) => Promise<void>;
+  redeem: (additionUpdate: AccountUpdate) => Promise<void>;
+}
+
+// Some random prefix for the sequencer signature
+export const BATCH_SIGNATURE_PREFIX = prefixToField("pk-batchSignature");
+
+export class SettlementSmartContract
+  extends TokenContract
+  implements SettlementContractType
+{
+  // 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: {
+    DispatchContract: TypedClass<DispatchContractType & SmartContract>;
+    hooks: ProvableSettlementHook<unknown>[];
+    withdrawalStatePath: [string, string];
+    escapeHatchSlotsInterval: number;
+  };
+
+  @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 outgoingMessageCursor = State<Field>();
+
+  @method async approveBase(forest: AccountUpdateForest) {
+    this.checkZeroBalanceChange(forest);
+  }
+
+  @method
+  public async initialize(sequencer: PublicKey, dispatchContract: PublicKey) {
+    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 } = SettlementSmartContract.args;
+    const contractInstance = new DispatchContract(dispatchContract);
+    await contractInstance.initialize(this.address);
+  }
+
+  @method
+  public async settle(
+    blockProof: LazyBlockProof,
+    signature: Signature,
+    dispatchContractAddress: PublicKey,
+    publicKey: PublicKey,
+    inputNetworkState: NetworkState,
+    outputNetworkState: NetworkState,
+    newPromisedMessagesHash: Field
+  ) {
+    // Verify the blockproof
+    blockProof.verify();
+
+    // 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 } =
+      SettlementSmartContract.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"
+    );
+
+    // 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);
+  }
+
+  @method
+  public async rollupOutgoingMessages(batch: OutgoingMessageArgumentBatch) {
+    let counter = this.outgoingMessageCursor.getAndRequireEquals();
+    const stateRoot = this.stateRoot.getAndRequireEquals();
+
+    const [withdrawalModule, withdrawalStateName] =
+      SettlementSmartContract.args.withdrawalStatePath;
+    const mapPath = Path.fromProperty(withdrawalModule, withdrawalStateName);
+
+    let accountCreationFeePaid = Field(0);
+
+    for (let i = 0; i < OUTGOING_MESSAGE_BATCH_SIZE; i++) {
+      const args = batch.arguments[i];
+
+      // Check witness
+      const path = Path.fromKey(mapPath, Field, counter);
+
+      args.witness
+        .checkMembership(
+          stateRoot,
+          path,
+          Poseidon.hash(Withdrawal.toFields(args.value))
+        )
+        .assertTrue("Provided Withdrawal witness not valid");
+
+      // Process message
+      const { address, amount } = args.value;
+      const isDummy = address.equals(this.address);
+
+      const tokenAu = this.internal.mint({ address, amount });
+      const isNewAccount = tokenAu.account.isNew.getAndRequireEquals();
+      tokenAu.body.balanceChange.magnitude =
+        tokenAu.body.balanceChange.magnitude.sub(
+          Provable.if(
+            isNewAccount,
+            Mina.getNetworkConstants().accountCreationFee.toConstant(),
+            UInt64.zero
+          )
+        );
+
+      accountCreationFeePaid = accountCreationFeePaid.add(
+        Provable.if(isNewAccount, Field(1e9), Field(0))
+      );
+
+      counter = counter.add(Provable.if(isDummy, Field(0), Field(1)));
+    }
+
+    this.balance.subInPlace(UInt64.Unsafe.fromField(accountCreationFeePaid));
+
+    this.outgoingMessageCursor.set(counter);
+  }
+
+  @method
+  public async redeem(additionUpdate: AccountUpdate) {
+    additionUpdate.body.tokenId.assertEquals(
+      TokenId.default,
+      "Tokenid not default token"
+    );
+    additionUpdate.body.balanceChange.sgn
+      .isPositive()
+      .assertTrue("Sign not correct");
+    const amount = additionUpdate.body.balanceChange.magnitude;
+
+    // Burn tokens
+    this.internal.burn({
+      address: additionUpdate.publicKey,
+      amount,
+    });
+
+    // Send mina
+    this.approve(additionUpdate);
+    this.balance.subInPlace(amount);
+  }
+}
+
+/* eslint-enable @typescript-eslint/lines-between-class-members */

package/src/settlement/messages/Deposit.ts

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

package/src/settlement/messages/OutgoingMessageArgument.ts

@@ -0,0 +1,42 @@
+import { Bool, Provable, Struct } from "o1js";
+import { RollupMerkleTreeWitness } from "@proto-kit/common";
+
+import { Withdrawal } from "./Withdrawal";
+
+export const OUTGOING_MESSAGE_BATCH_SIZE = 1;
+
+export class OutgoingMessageArgument extends Struct({
+  witness: RollupMerkleTreeWitness,
+  value: Withdrawal,
+}) {
+  public static dummy(): OutgoingMessageArgument {
+    return new OutgoingMessageArgument({
+      witness: RollupMerkleTreeWitness.dummy(),
+      value: Withdrawal.dummy(),
+    });
+  }
+}
+
+export class OutgoingMessageArgumentBatch extends Struct({
+  arguments: Provable.Array(
+    OutgoingMessageArgument,
+    OUTGOING_MESSAGE_BATCH_SIZE
+  ),
+
+  isDummys: Provable.Array(Bool, OUTGOING_MESSAGE_BATCH_SIZE),
+}) {
+  public static fromMessages(providedArguments: OutgoingMessageArgument[]) {
+    const batch = providedArguments.slice();
+    const isDummys = batch.map(() => Bool(false));
+
+    while (batch.length < OUTGOING_MESSAGE_BATCH_SIZE) {
+      batch.push(OutgoingMessageArgument.dummy());
+      isDummys.push(Bool(true));
+    }
+
+    return new OutgoingMessageArgumentBatch({
+      arguments: batch,
+      isDummys,
+    });
+  }
+}

package/src/settlement/messages/Withdrawal.ts

@@ -0,0 +1,14 @@
+import { PublicKey, Struct, UInt64 } from "o1js";
+import { EMPTY_PUBLICKEY } from "@proto-kit/common";
+
+export class Withdrawal extends Struct({
+  address: PublicKey,
+  amount: UInt64,
+}) {
+  public static dummy() {
+    return new Withdrawal({
+      address: EMPTY_PUBLICKEY,
+      amount: UInt64.from(0),
+    });
+  }
+}

package/src/settlement/modularity/ProvableSettlementHook.ts

@@ -0,0 +1,33 @@
+import { Field, PublicKey, UInt32 } from "o1js";
+
+import { ProtocolModule } from "../../protocol/ProtocolModule";
+import { NetworkState } from "../../model/network/NetworkState";
+import type { BlockProof } from "../../prover/block/BlockProver";
+import type { SettlementSmartContract } from "../contracts/SettlementSmartContract";
+
+export type SettlementStateRecord = {
+  sequencerKey: PublicKey;
+  lastSettlementL1BlockHeight: UInt32;
+
+  stateRoot: Field;
+  networkStateHash: Field;
+  blockHashRoot: Field;
+};
+
+export type SettlementHookInputs = {
+  blockProof: BlockProof;
+  fromNetworkState: NetworkState;
+  toNetworkState: NetworkState;
+  newPromisedMessagesHash: Field;
+  contractState: SettlementStateRecord;
+  currentL1BlockHeight: UInt32;
+};
+
+export abstract class ProvableSettlementHook<
+  Config,
+> extends ProtocolModule<Config> {
+  public abstract beforeSettlement(
+    smartContract: SettlementSmartContract,
+    inputs: SettlementHookInputs
+  ): Promise<void>;
+}