@proto-kit/protocol 0.1.1-develop.0

package/src/hooks/NoopBlockHook.ts

@@ -0,0 +1,21 @@
+import { NoConfig } from "@proto-kit/common";
+
+import { ProvableBlockHook } from "../protocol/ProvableBlockHook";
+import { NetworkState } from "../model/network/NetworkState";
+import { BlockProverState } from "../prover/block/BlockProver";
+
+export class NoopBlockHook extends ProvableBlockHook<NoConfig> {
+  public async afterBlock(
+    networkState: NetworkState,
+    state: BlockProverState
+  ): Promise<NetworkState> {
+    return networkState;
+  }
+
+  public async beforeBlock(
+    networkState: NetworkState,
+    state: BlockProverState
+  ): Promise<NetworkState> {
+    return networkState;
+  }
+}

package/src/hooks/NoopSettlementHook.ts

@@ -0,0 +1,20 @@
+import { injectable } from "tsyringe";
+import { noop } from "@proto-kit/common";
+
+import {
+  ProvableSettlementHook,
+  SettlementHookInputs,
+} from "../settlement/modularity/ProvableSettlementHook";
+import { SettlementSmartContractBase } from "../settlement/contracts/SettlementSmartContract";
+
+@injectable()
+export class NoopSettlementHook extends ProvableSettlementHook<
+  Record<string, never>
+> {
+  public async beforeSettlement(
+    contract: SettlementSmartContractBase,
+    state: SettlementHookInputs
+  ) {
+    noop();
+  }
+}

package/src/hooks/NoopTransactionHook.ts

@@ -0,0 +1,10 @@
+import { noop } from "@proto-kit/common";
+
+import { ProvableTransactionHook } from "../protocol/ProvableTransactionHook";
+import { BlockProverExecutionData } from "../prover/block/BlockProvable";
+
+export class NoopTransactionHook extends ProvableTransactionHook {
+  public async onTransaction(executionData: BlockProverExecutionData) {
+    noop();
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+export * from "./hooks/AccountStateHook";
+export * from "./hooks/BlockHeightHook";
+export * from "./hooks/LastStateRootBlockHook";
+export * from "./model/StateTransition";
+export * from "./model/StateTransitionProvableBatch";
+export * from "./model/Option";
+export * from "./model/Path";
+export * from "./model/network/NetworkState";
+export * from "./model/transaction/SignedTransaction";
+export * from "./model/transaction/RuntimeTransaction";
+export * from "./model/transaction/ValueOption";
+export * from "./model/MethodPublicOutput";
+export * from "./model/RuntimeLike";
+export * from "./utils/ProvableHashList";
+export * from "./utils/PrefixedProvableHashList";
+export * from "./utils/MinaPrefixedProvableHashList";
+export * from "./utils/ProvableReductionHashList";
+export * from "./utils/StateTransitionReductionList";
+export * from "./utils/utils";
+export * from "./prover/block/BlockProver";
+export * from "./prover/block/BlockProvable";
+export * from "./prover/block/accummulators/RuntimeVerificationKeyTree";
+export * from "./prover/block/accummulators/BlockHashMerkleTree";
+export * from "./prover/block/services/RuntimeVerificationKeyRootService";
+export * from "./prover/statetransition/StateTransitionProver";
+export * from "./prover/statetransition/StateTransitionProvable";
+export * from "./protocol/Protocol";
+export * from "./protocol/ProtocolModule";
+export * from "./protocol/ProtocolEnvironment";
+export * from "./protocol/ProvableTransactionHook";
+export * from "./protocol/ProvableBlockHook";
+export * from "./state/context/TransitionMethodExecutionContext";
+export * from "./state/context/RuntimeMethodExecutionContext";
+export * from "./state/protocol/ProtocolState";
+export * from "./state/State";
+export * from "./state/StateMap";
+export * from "./state/StateService";
+export * from "./state/StateServiceProvider";
+export * from "./state/assert/assert";
+export * from "./settlement/contracts/authorizations/ContractAuthorization";
+export * from "./settlement/contracts/authorizations/UpdateMessagesHashAuth";
+export * from "./settlement/contracts/authorizations/TokenBridgeDeploymentAuth";
+export * from "./settlement/contracts/SettlementSmartContract";
+export * from "./settlement/contracts/SettlementContractProtocolModule";
+export * from "./settlement/contracts/DispatchSmartContract";
+export * from "./settlement/contracts/DispatchContractProtocolModule";
+export * from "./settlement/contracts/BridgeContract";
+export * from "./settlement/contracts/BridgeContractProtocolModule";
+export * from "./settlement/contracts/TokenBridgeTree";
+export * from "./settlement/SettlementContractModule";
+export * from "./settlement/ContractModule";
+export * from "./settlement/modularity/ProvableSettlementHook";
+export * from "./settlement/messages/OutgoingMessageArgument";
+export * from "./settlement/modules/NetworkStateSettlementModule";
+export * from "./settlement/messages/Deposit";
+export * from "./settlement/messages/Withdrawal";
+export { constants as ProtocolConstants } from "./Constants";

package/src/model/MethodPublicOutput.ts

@@ -0,0 +1,14 @@
+import { Bool, Field, Struct } from "o1js";
+
+/**
+ * Public input used to link in-circuit execution with
+ * the proof's public input.
+ */
+export class MethodPublicOutput extends Struct({
+  stateTransitionsHash: Field,
+  status: Bool,
+  transactionHash: Field,
+  networkStateHash: Field,
+  isMessage: Bool,
+  eventsHash: Field,
+}) {}

package/src/model/Option.ts

@@ -0,0 +1,172 @@
+import {
+  Bool,
+  Field,
+  type FlexibleProvablePure,
+  Poseidon,
+  Provable,
+  ProvablePure,
+  Struct,
+} from "o1js";
+
+export class ProvableOption extends Struct({
+  isSome: Bool,
+  value: Field,
+}) {
+  public toSome() {
+    this.isSome = Bool(true);
+    return this;
+  }
+}
+
+export abstract class OptionBase {
+  protected constructor(
+    public isSome: Bool,
+    public isForcedSome: Bool
+  ) {}
+
+  protected abstract encodeValueToFields(): Field[];
+
+  protected abstract clone(): OptionBase;
+
+  /**
+   * @returns Tree representation of the current value
+   */
+  public get treeValue() {
+    const treeValue = Poseidon.hash(this.encodeValueToFields());
+
+    return Provable.if(
+      this.isSome.and(this.isForcedSome.not()),
+      treeValue,
+      Field(0)
+    );
+  }
+
+  public forceSome() {
+    this.isForcedSome = Provable.if(this.isSome, Bool(false), Bool(true));
+    this.isSome = Bool(true);
+  }
+
+  /**
+   * Returns the `to`-value as decoded as a list of fields
+   * Not in circuit
+   */
+  public toFields(): Field[] {
+    if (this.isSome.toBoolean()) {
+      return this.encodeValueToFields();
+    }
+    return [Field(0)];
+  }
+
+  /**
+   * @returns Provable representation of the current option.
+   */
+  public toProvable() {
+    return new ProvableOption({
+      isSome: this.isSome,
+      value: this.treeValue,
+    });
+  }
+
+  public toJSON() {
+    const value = this.encodeValueToFields().map((field) => field.toString());
+
+    return {
+      isSome: this.isSome.toBoolean(),
+      isForcedSome: this.isForcedSome.toBoolean(),
+      value,
+    };
+  }
+}
+
+/**
+ * Option facilitating in-circuit values that may or may not exist.
+ */
+export class Option<Value> extends OptionBase {
+  /**
+   * Creates a new Option from the provided parameters
+   *
+   * @param isSome
+   * @param value
+   * @param valueType
+   * @returns New option from the provided parameters.
+   */
+  public static from<Value>(
+    isSome: Bool,
+    value: Value,
+    valueType: FlexibleProvablePure<Value>
+  ) {
+    return new Option(isSome, value, valueType);
+  }
+
+  /**
+   * Creates a new Option from the provided parameters
+   *
+   * @param value
+   * @param valueType
+   * @returns New option from the provided parameters.
+   */
+  public static fromValue<Value>(
+    value: Value,
+    valueType: FlexibleProvablePure<Value>
+  ) {
+    return this.from(Bool(true), value, valueType);
+  }
+
+  /**
+   * @returns Empty / none option
+   */
+  public static none() {
+    return new Option(Bool(false), Field(0), Field);
+  }
+
+  public constructor(
+    isSome: Bool,
+    public value: Value,
+    public valueType: FlexibleProvablePure<Value>,
+    isForcedSome = Bool(false)
+  ) {
+    super(isSome, isForcedSome);
+  }
+
+  public encodeValueToFields(): Field[] {
+    return this.valueType.toFields(this.value);
+  }
+
+  public clone(): Option<Value> {
+    return new Option(
+      this.isSome,
+      this.value,
+      this.valueType,
+      this.isForcedSome
+    );
+  }
+
+  /**
+   * @returns Returns the value of this option if it isSome,
+   * otherwise returns the given defaultValue
+   */
+  public orElse(defaultValue: Value): Value {
+    return Provable.if<Value>(
+      this.isSome,
+      this.valueType,
+      this.value,
+      defaultValue
+    );
+  }
+
+  public toConstant() {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const valueConstant = (this.valueType as ProvablePure<Value>).fromFields(
+      this.valueType.toFields(this.value).map((field) => field.toConstant())
+    );
+    const boolConstant = (bool: Bool) =>
+      Bool.fromFields([bool.toField().toConstant()]);
+
+    return new Option(
+      boolConstant(this.isSome),
+      valueConstant,
+      this.valueType,
+      boolConstant(this.isForcedSome)
+    );
+  }
+}

package/src/model/Path.ts

@@ -0,0 +1,50 @@
+import { Field, type FlexibleProvablePure, Poseidon } from "o1js";
+
+import { stringToField } from "../utils/utils";
+
+/**
+ * Helps manage path (key) identifiers for key-values in trees.
+ */
+export class Path {
+  /**
+   * Encodes a JS string as a Field
+   *
+   * @param value
+   * @returns Field representation of the provided value
+   */
+  public static toField(value: string) {
+    return stringToField(value);
+  }
+
+  /**
+   * Encodes a class name and its property name into a Field
+   *
+   * @param className
+   * @param propertyKey
+   * @returns Field representation of class name + property name
+   */
+  public static fromProperty(className: string, propertyKey: string): Field {
+    return Poseidon.hash([
+      Path.toField(className),
+      Path.toField(propertyKey),
+      Field(0),
+    ]);
+  }
+
+  /**
+   * Encodes an existing path with the provided key into a single Field.
+   *
+   * @param path
+   * @param keyType
+   * @param key
+   * @returns Field representation of the leading path + the provided key.
+   */
+  public static fromKey<KeyType>(
+    path: Field,
+    keyType: FlexibleProvablePure<KeyType>,
+    key: KeyType
+  ): Field {
+    const keyHash = Poseidon.hash(keyType.toFields(key));
+    return Poseidon.hash([path, keyHash]);
+  }
+}

package/src/model/RuntimeLike.ts

@@ -0,0 +1,12 @@
+export type RuntimeMethodInvocationType = "INCOMING_MESSAGE" | "SIGNATURE";
+
+export type RuntimeMethodIdMapping = Record<
+  `${string}.${string}`,
+  { methodId: bigint; type: RuntimeMethodInvocationType }
+>;
+
+export interface RuntimeLike {
+  get methodIdResolver(): {
+    methodIdMap: () => RuntimeMethodIdMapping;
+  };
+}

package/src/model/StateTransition.ts

@@ -0,0 +1,88 @@
+import { Field, Struct } from "o1js";
+
+import { Option, ProvableOption } from "./Option";
+
+/**
+ * Provable representation of a State Transition, used to
+ * normalize state transitions of various value types for
+ * the state transition circuit.
+ */
+export class ProvableStateTransition extends Struct({
+  path: Field,
+
+  // must be applied even if `None`
+  from: ProvableOption,
+
+  // must be ignored if `None`
+  to: ProvableOption,
+}) {
+  public static dummy(): ProvableStateTransition {
+    return new ProvableStateTransition({
+      path: Field(0),
+      from: Option.none().toProvable(),
+      to: Option.none().toProvable(),
+    });
+  }
+}
+
+/**
+ * Generic state transition that constraints the current method circuit
+ * to external state, by providing a state anchor.
+ */
+export class StateTransition<Value> {
+  public static from<Value>(path: Field, fromValue: Option<Value>) {
+    return new StateTransition(path, fromValue, Option.none());
+  }
+
+  public static fromTo<Value>(
+    path: Field,
+    fromValue: Option<Value>,
+    toValue: Option<Value>
+  ) {
+    return new StateTransition(path, fromValue, toValue);
+  }
+
+  public constructor(
+    public path: Field,
+    public fromValue: Option<Value>,
+    public toValue: Option<Field> | Option<Value>
+  ) {}
+
+  public get from() {
+    const from = this.fromValue.clone();
+    from.forceSome();
+    return from;
+  }
+
+  public get to() {
+    return this.toValue.clone();
+  }
+
+  /**
+   * Converts a StateTransition to a ProvableStateTransition,
+   * while enforcing the 'from' property to be 'Some' in all cases.
+   */
+  public toProvable(): ProvableStateTransition {
+    return new ProvableStateTransition({
+      path: this.path,
+      from: this.from.toProvable(),
+      to: this.to.toProvable(),
+    });
+  }
+
+  public toJSON() {
+    return {
+      path: this.path.toString(),
+      from: this.fromValue.toJSON(),
+      to: this.toValue.toJSON(),
+    };
+  }
+
+  public toConstant(): StateTransition<Value> {
+    return new StateTransition<Value>(
+      this.path.toConstant(),
+      this.fromValue.toConstant(),
+      this.toValue.toConstant()
+    );
+  }
+}

package/src/model/StateTransitionProvableBatch.ts

@@ -0,0 +1,145 @@
+import { Bool, Provable, Struct } from "o1js";
+import {
+  InMemoryMerkleTreeStorage,
+  range,
+  RollupMerkleTree,
+  RollupMerkleTreeWitness,
+} from "@proto-kit/common";
+
+import { constants } from "../Constants";
+
+import { ProvableStateTransition } from "./StateTransition.js";
+
+export class StateTransitionType {
+  public static readonly normal = true;
+
+  public static readonly protocol = false;
+
+  public static isNormal(type: boolean) {
+    return type === StateTransitionType.normal;
+  }
+
+  public static isProtocol(type: boolean) {
+    return type === StateTransitionType.protocol;
+  }
+}
+
+export class ProvableStateTransitionType extends Struct({
+  type: Bool,
+}) {
+  public static get normal(): ProvableStateTransitionType {
+    return new ProvableStateTransitionType({
+      type: Bool(StateTransitionType.normal),
+    });
+  }
+
+  public static get protocol(): ProvableStateTransitionType {
+    return new ProvableStateTransitionType({
+      type: Bool(StateTransitionType.protocol),
+    });
+  }
+
+  public isNormal(): Bool {
+    return this.type;
+  }
+
+  public isProtocol(): Bool {
+    return this.type.not();
+  }
+}
+
+/**
+ * A Batch of StateTransitions to be consumed by the StateTransitionProver
+ * to prove multiple STs at once
+ *
+ * transitionType:
+ * true == normal ST, false == protocol ST
+ */
+export class StateTransitionProvableBatch extends Struct({
+  batch: Provable.Array(
+    ProvableStateTransition,
+    constants.stateTransitionProverBatchSize
+  ),
+
+  transitionTypes: Provable.Array(
+    ProvableStateTransitionType,
+    constants.stateTransitionProverBatchSize
+  ),
+
+  merkleWitnesses: Provable.Array(
+    RollupMerkleTreeWitness,
+    constants.stateTransitionProverBatchSize
+  ),
+}) {
+  public static fromMappings(
+    transitions: {
+      transition: ProvableStateTransition;
+      type: ProvableStateTransitionType;
+    }[],
+    merkleWitnesses: RollupMerkleTreeWitness[]
+  ): StateTransitionProvableBatch {
+    const batch = transitions.map((entry) => entry.transition);
+    const transitionTypes = transitions.map((entry) => entry.type);
+    const witnesses = merkleWitnesses.slice();
+    // Check that order is correct
+    let normalSTsStarted = false;
+    transitionTypes.forEach((x) => {
+      if (!normalSTsStarted && x.isNormal().toBoolean()) {
+        normalSTsStarted = true;
+      }
+      if (normalSTsStarted && x.isProtocol().toBoolean()) {
+        throw new Error("Order in initializing STBatch not correct");
+      }
+    });
+
+    while (batch.length < constants.stateTransitionProverBatchSize) {
+      batch.push(ProvableStateTransition.dummy());
+      transitionTypes.push(ProvableStateTransitionType.normal);
+      witnesses.push(
+        new RollupMerkleTree(new InMemoryMerkleTreeStorage()).getWitness(
+          BigInt(0)
+        )
+      );
+    }
+    return new StateTransitionProvableBatch({
+      batch,
+      transitionTypes,
+      merkleWitnesses: witnesses,
+    });
+  }
+
+  public static fromTransitions(
+    transitions: ProvableStateTransition[],
+    protocolTransitions: ProvableStateTransition[],
+    merkleWitnesses: RollupMerkleTreeWitness[]
+  ): StateTransitionProvableBatch {
+    const array = transitions.slice().concat(protocolTransitions);
+
+    const transitionTypes = range(0, transitions.length)
+      .map(() => ProvableStateTransitionType.normal)
+      .concat(
+        range(0, protocolTransitions.length).map(
+          () => ProvableStateTransitionType.protocol
+        )
+      );
+
+    while (array.length < constants.stateTransitionProverBatchSize) {
+      array.push(ProvableStateTransition.dummy());
+      transitionTypes.push(ProvableStateTransitionType.normal);
+    }
+
+    return new StateTransitionProvableBatch({
+      batch: array,
+      transitionTypes,
+      merkleWitnesses,
+    });
+  }
+
+  private constructor(object: {
+    batch: ProvableStateTransition[];
+    transitionTypes: ProvableStateTransitionType[];
+    merkleWitnesses: RollupMerkleTreeWitness[];
+  }) {
+    super(object);
+  }
+}

package/src/model/Transaction.ts

@@ -0,0 +1,31 @@
+import {
+  Field,
+  FlexibleProvable,
+  Poseidon,
+  PublicKey,
+  Signature,
+  Struct,
+  UInt64,
+} from "o1js";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function argsToHash(...args: FlexibleProvable<any>[]): Field {
+  const fields = args.flatMap((argument) => argument.toFields(argument));
+  return Poseidon.hash(fields);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+class Transaction extends Struct({
+  // must be checked inside @runtimeMethod
+  methodId: Field,
+  // constructed by hashing args + appending all used proof input/output hashes at the end
+  argsHash: Field,
+  // must (due to nonce) be checked during applyTransaction
+  nonce: UInt64,
+  sender: PublicKey,
+  signature: Signature,
+}) {
+  public toHash(): Field {
+    return Poseidon.hash(Transaction.toFields(this));
+  }
+}

package/src/model/network/NetworkState.ts

@@ -0,0 +1,33 @@
+import { Field, Poseidon, Struct, UInt64 } from "o1js";
+import { RollupMerkleTree } from "@proto-kit/common";
+
+export class CurrentBlock extends Struct({
+  height: UInt64,
+}) {}
+
+export class PreviousBlock extends Struct({
+  rootHash: Field,
+}) {}
+
+export class NetworkState extends Struct({
+  block: CurrentBlock,
+  previous: PreviousBlock,
+}) {
+  public hash(): Field {
+    return Poseidon.hash([
+      ...CurrentBlock.toFields(this.block),
+      ...PreviousBlock.toFields(this.previous),
+    ]);
+  }
+
+  public static empty() {
+    return new NetworkState({
+      block: {
+        height: UInt64.zero,
+      },
+      previous: {
+        rootHash: Field(RollupMerkleTree.EMPTY_ROOT),
+      },
+    });
+  }
+}