@proto-kit/protocol 0.1.1-develop.1086

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,125 @@
+import { Bool, Provable, Struct } from "o1js";
+import { range } 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
+  ),
+}) {
+  public static fromMappings(
+    transitions: {
+      transition: ProvableStateTransition;
+      type: ProvableStateTransitionType;
+    }[]
+  ): StateTransitionProvableBatch {
+    const batch = transitions.map((entry) => entry.transition);
+    const transitionTypes = transitions.map((entry) => entry.type);
+
+    // 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);
+    }
+    return new StateTransitionProvableBatch({
+      batch,
+      transitionTypes,
+    });
+  }
+
+  public static fromTransitions(
+    transitions: ProvableStateTransition[],
+    protocolTransitions: ProvableStateTransition[]
+  ): 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,
+    });
+  }
+
+  private constructor(object: {
+    batch: ProvableStateTransition[];
+    transitionTypes: ProvableStateTransitionType[];
+  }) {
+    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),
+      },
+    });
+  }
+}

package/src/model/transaction/RuntimeTransaction.ts

@@ -0,0 +1,105 @@
+import { Bool, Field, Poseidon, PublicKey, Struct, UInt64 } from "o1js";
+import { EMPTY_PUBLICKEY, EMPTY_PUBLICKEY_X } from "@proto-kit/common";
+
+import { PublicKeyOption, UInt64Option } from "./ValueOption";
+
+/**
+ * This struct is used to expose transaction information to the runtime method
+ * execution. This class has not all data included in transactions on purpose.
+ * For example, we don't want to expose the signature or args as fields.
+ */
+export class RuntimeTransaction extends Struct({
+  methodId: Field,
+  argsHash: Field,
+  nonce: UInt64Option,
+  sender: PublicKeyOption,
+}) {
+  public static fromTransaction(input: {
+    methodId: Field;
+    argsHash: Field;
+    nonce: UInt64;
+    sender: PublicKey;
+  }) {
+    return new RuntimeTransaction({
+      methodId: input.methodId,
+      argsHash: input.argsHash,
+      nonce: UInt64Option.fromSome(input.nonce),
+      sender: PublicKeyOption.fromSome(input.sender),
+    });
+  }
+
+  public static fromMessage({
+    methodId,
+    argsHash,
+  }: {
+    methodId: Field;
+    argsHash: Field;
+  }) {
+    return new RuntimeTransaction({
+      methodId,
+      argsHash,
+      nonce: UInt64Option.none(UInt64.zero),
+      sender: PublicKeyOption.none(EMPTY_PUBLICKEY),
+    });
+  }
+
+  public static dummyTransaction(): RuntimeTransaction {
+    return new RuntimeTransaction({
+      methodId: Field(0),
+      nonce: new UInt64Option({
+        isSome: Bool(true),
+        value: UInt64.zero,
+      }),
+      sender: new PublicKeyOption({
+        isSome: Bool(true),
+        value: EMPTY_PUBLICKEY,
+      }),
+      argsHash: Field(0),
+    });
+  }
+
+  public assertTransactionType(isMessage: Bool) {
+    const isTransaction = isMessage.not();
+    // isSome has to be true when it is a transaction, otherwise false
+    this.nonce.isSome
+      .equals(isTransaction)
+      .assertTrue("Nonce is not right option isSome for type");
+    this.sender.isSome
+      .equals(isTransaction)
+      .assertTrue("Sender is not right option isSome for type");
+    this.sender.value.x
+      .equals(EMPTY_PUBLICKEY_X)
+      .equals(isMessage)
+      .assertTrue("Transaction sender is not set to dummy");
+  }
+
+  public hashData(): Field[] {
+    return [
+      this.methodId,
+      ...this.sender.value.toFields(),
+      ...this.nonce.value.toFields(),
+      this.argsHash,
+    ];
+  }
+
+  public static fromHashData(fields: Field[]) {
+    // sender is 2nd and the first element is x (2nd isOdd)
+    const isMessage = fields[1].equals(EMPTY_PUBLICKEY_X);
+    return new RuntimeTransaction({
+      methodId: fields[0],
+      sender: new PublicKeyOption({
+        isSome: isMessage.not(),
+        value: PublicKey.fromFields([fields[1], fields[2]]),
+      }),
+      nonce: new UInt64Option({
+        isSome: isMessage.not(),
+        value: UInt64.fromFields([fields[3]]),
+      }),
+      argsHash: fields[4],
+    });
+  }
+
+  public hash(): Field {
+    return Poseidon.hash(this.hashData());
+  }
+}

package/src/model/transaction/SignedTransaction.ts

@@ -0,0 +1,47 @@
+import { Bool, Field, Scalar, Signature, Struct, UInt64 } from "o1js";
+
+import { RuntimeTransaction } from "./RuntimeTransaction";
+
+export class SignedTransaction extends Struct({
+  transaction: RuntimeTransaction,
+  signature: Signature,
+}) {
+  public static getSignatureData(args: {
+    methodId: Field;
+    nonce: UInt64;
+    argsHash: Field;
+  }): Field[] {
+    return [args.methodId, ...args.nonce.value.toFields(), args.argsHash];
+  }
+
+  public static dummy(): SignedTransaction {
+    return new SignedTransaction({
+      transaction: RuntimeTransaction.dummyTransaction(),
+
+      signature: Signature.fromObject({
+        s: Scalar.from(0),
+        r: Field(0),
+      }),
+    });
+  }
+
+  public hash(): Field {
+    return this.transaction.hash();
+  }
+
+  public getSignatureData(): Field[] {
+    const { methodId, argsHash, nonce } = this.transaction;
+    return SignedTransaction.getSignatureData({
+      nonce: nonce.value,
+      methodId,
+      argsHash,
+    });
+  }
+
+  public validateSignature(): Bool {
+    return this.signature.verify(
+      this.transaction.sender.value,
+      this.getSignatureData()
+    );
+  }
+}

package/src/model/transaction/ValueOption.ts

@@ -0,0 +1,28 @@
+import { Bool, ProvableExtended, PublicKey, Struct, UInt64 } from "o1js";
+
+function genericOptionFactory<Type>(valueType: ProvableExtended<Type>) {
+  return class Generic extends Struct({
+    isSome: Bool,
+    value: valueType,
+  }) {
+    public static fromSome(value: Type) {
+      return new Generic({
+        isSome: Bool(true),
+        value,
+      });
+    }
+
+    public static none(value: Type) {
+      return new Generic({
+        isSome: Bool(false),
+        value,
+      });
+    }
+  };
+}
+
+export class UInt64Option extends genericOptionFactory<UInt64>(UInt64) {}
+
+export class PublicKeyOption extends genericOptionFactory<PublicKey>(
+  PublicKey
+) {}

package/src/protocol/Protocol.ts

@@ -0,0 +1,197 @@
+import {
+  AreProofsEnabled,
+  ChildContainerProvider,
+  log,
+  ModuleContainer,
+  ModulesConfig,
+  ModulesRecord,
+  StringKeyOf,
+  TypedClass,
+} from "@proto-kit/common";
+import { DependencyContainer, Lifecycle } from "tsyringe";
+
+import { BlockProvable } from "../prover/block/BlockProvable";
+import { StateTransitionProvable } from "../prover/statetransition/StateTransitionProvable";
+import { StateServiceProvider } from "../state/StateServiceProvider";
+import { SimpleAsyncStateService } from "../state/StateService";
+import { NoopBlockHook } from "../hooks/NoopBlockHook";
+import { BlockHeightHook } from "../hooks/BlockHeightHook";
+import { LastStateRootBlockHook } from "../hooks/LastStateRootBlockHook";
+import { ProvableSettlementHook } from "../settlement/modularity/ProvableSettlementHook";
+import { NoopSettlementHook } from "../hooks/NoopSettlementHook";
+import { AccountStateHook } from "../hooks/AccountStateHook";
+import { NoopTransactionHook } from "../hooks/NoopTransactionHook";
+
+import { ProtocolModule } from "./ProtocolModule";
+import { ProvableTransactionHook } from "./ProvableTransactionHook";
+import { ProtocolEnvironment } from "./ProtocolEnvironment";
+import { ProvableBlockHook } from "./ProvableBlockHook";
+
+const PROTOCOL_INJECTION_TOKENS: Record<string, string> = {
+  ProvableTransactionHook: "ProvableTransactionHook",
+  ProvableBlockHook: "ProvableBlockHook",
+  ProvableSettlementHook: "ProvableSettlementHook",
+};
+
+export type ProtocolModulesRecord = ModulesRecord<
+  TypedClass<ProtocolModule<unknown>>
+>;
+
+export interface BlockProverType extends ProtocolModule, BlockProvable {}
+
+export interface StateTransitionProverType
+  extends ProtocolModule,
+    StateTransitionProvable {}
+
+export type MandatoryProtocolModulesRecord = {
+  BlockProver: TypedClass<BlockProverType>;
+  StateTransitionProver: TypedClass<StateTransitionProverType>;
+  AccountState: TypedClass<AccountStateHook>;
+  BlockHeight: TypedClass<BlockHeightHook>;
+  LastStateRoot: TypedClass<LastStateRootBlockHook>;
+};
+
+export interface ProtocolDefinition<Modules extends ProtocolModulesRecord> {
+  modules: Modules;
+  config?: ModulesConfig<Modules>;
+}
+
+export class Protocol<
+    Modules extends ProtocolModulesRecord & MandatoryProtocolModulesRecord,
+  >
+  extends ModuleContainer<Modules>
+  implements ProtocolEnvironment
+{
+  public static from<
+    Modules extends ProtocolModulesRecord & MandatoryProtocolModulesRecord,
+  >(modules: ProtocolDefinition<Modules>): TypedClass<Protocol<Modules>> {
+    return class ScopedProtocol extends Protocol<Modules> {
+      public constructor() {
+        super(modules);
+      }
+    };
+  }
+
+  public definition: ProtocolDefinition<Modules>;
+
+  public constructor(definition: ProtocolDefinition<Modules>) {
+    super(definition);
+    this.definition = definition;
+  }
+
+  public get stateService(): SimpleAsyncStateService {
+    return this.stateServiceProvider.stateService;
+  }
+
+  public get stateServiceProvider(): StateServiceProvider {
+    return this.container.resolve<StateServiceProvider>("StateServiceProvider");
+  }
+
+  public decorateModule(
+    moduleName: StringKeyOf<Modules>,
+    containedModule: InstanceType<Modules[StringKeyOf<Modules>]>
+  ) {
+    log.debug(`Decorated ${moduleName}`);
+    containedModule.protocol = this;
+
+    if (containedModule instanceof ProvableTransactionHook) {
+      containedModule.name = moduleName;
+    }
+
+    super.decorateModule(moduleName, containedModule);
+  }
+
+  public get dependencyContainer(): DependencyContainer {
+    return this.container;
+  }
+
+  private isModule(
+    moduleName: keyof Modules
+  ): moduleName is StringKeyOf<Modules> {
+    return this.definition.modules[moduleName] !== undefined;
+  }
+
+  public get blockProver(): BlockProvable {
+    // Why do I resolve directly here?
+    // I don't know exactly but generics don't let me use .resolve()
+    return this.container.resolve<InstanceType<Modules["BlockProver"]>>(
+      "BlockProver"
+    );
+  }
+
+  public get stateTransitionProver(): StateTransitionProvable {
+    return this.container.resolve<
+      InstanceType<Modules["StateTransitionProver"]>
+    >("StateTransitionProver");
+  }
+
+  public getAreProofsEnabled(): AreProofsEnabled {
+    return this.container.resolve<AreProofsEnabled>("AreProofsEnabled");
+  }
+
+  public create(childContainerProvider: ChildContainerProvider) {
+    super.create(childContainerProvider);
+
+    // Register the BlockModules seperately since we need to
+    // inject them differently later
+    const ABSTRACT_MODULE_TYPES = [
+      { type: ProvableTransactionHook, defaultType: NoopTransactionHook },
+      { type: ProvableBlockHook, defaultType: NoopBlockHook },
+      { type: ProvableSettlementHook, defaultType: NoopSettlementHook },
+    ] as const;
+
+    ABSTRACT_MODULE_TYPES.forEach((moduleTypeRegistration) => {
+      const abstractType = moduleTypeRegistration.type;
+
+      const implementingModules = Object.entries(
+        this.definition.modules
+      ).filter(([, value]) =>
+        Object.prototype.isPrototypeOf.call(abstractType, value)
+      );
+
+      const newInjectionToken: string | undefined =
+        PROTOCOL_INJECTION_TOKENS[abstractType.name];
+
+      if (newInjectionToken === undefined) {
+        log.error(
+          "Can't inject hook under the underlying hook token: Alias not found in mapping"
+        );
+        return;
+      }
+
+      implementingModules.forEach(([key]) => {
+        this.container.register(
+          abstractType.name,
+          { useToken: key },
+          { lifecycle: Lifecycle.ContainerScoped }
+        );
+      });
+      if (implementingModules.length === 0) {
+        // This type annotation shouldn't change anything but is necessary
+        // bcs tsyringe complains
+        const { defaultType }: { defaultType: TypedClass<unknown> } =
+          moduleTypeRegistration;
+
+        // Register default (noop) version
+        this.container.register(
+          abstractType.name,
+          { useClass: defaultType },
+          { lifecycle: Lifecycle.ContainerScoped }
+        );
+      }
+    });
+  }
+
+  public async start() {
+    // eslint-disable-next-line guard-for-in
+    for (const moduleName in this.definition.modules) {
+      const protocolModule = this.resolve(moduleName);
+
+      log.info(
+        `Starting protocol module ${moduleName} (${protocolModule.constructor.name})`
+      );
+      // eslint-disable-next-line no-await-in-loop
+      await protocolModule.start();
+    }
+  }
+}

package/src/protocol/ProtocolEnvironment.ts

@@ -0,0 +1,10 @@
+import { AreProofsEnabled } from "@proto-kit/common";
+
+import { SimpleAsyncStateService } from "../state/StateService";
+import { StateServiceProvider } from "../state/StateServiceProvider";
+
+export interface ProtocolEnvironment {
+  get stateService(): SimpleAsyncStateService;
+  get stateServiceProvider(): StateServiceProvider;
+  getAreProofsEnabled(): AreProofsEnabled;
+}