@proto-kit/protocol 0.1.1-develop.0

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,226 @@
+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";
+import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
+
+/**
+ * This is a mapping of abstract classes to their respective injection tokens.
+ * Keys are the abstract classes names, which need to be set dynamically
+ * and can't be hardcoded since producing optimized builds may mangle the
+ * class names, making them different from the ones in the source code.
+ */
+const PROTOCOL_INJECTION_TOKENS: Record<string, string> = {
+  [ProvableTransactionHook.name]: "ProvableTransactionHook",
+  [ProvableBlockHook.name]: "ProvableBlockHook",
+  [ProvableSettlementHook.name]: "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 TransitioningProtocolModule) {
+      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(
+          newInjectionToken,
+          { 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(
+          newInjectionToken,
+          { useClass: defaultType },
+          { lifecycle: Lifecycle.ContainerScoped }
+        );
+      }
+    });
+
+    // Cross-register all runtime modules to the protocol container for easier
+    // access of runtime modules inside protocol hooks
+    if (this.container.isRegistered("Runtime", true)) {
+      const runtimeContainer: ModuleContainer<any> =
+        this.container.resolve("Runtime");
+
+      runtimeContainer.moduleNames.forEach((runtimeModuleName) => {
+        this.container.register(runtimeModuleName, {
+          useFactory: (dependencyContainer) => {
+            // Prevents creation of closure
+            const runtime: ModuleContainer<any> =
+              dependencyContainer.resolve("Runtime");
+            return runtime.resolve(runtimeModuleName);
+          },
+        });
+      });
+    } else {
+      log.warn(
+        "Couldn't resolve Runtime reference in Protocol, resolving RuntimeModules in hooks won't be available"
+      );
+    }
+  }
+
+  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;
+}

package/src/protocol/ProtocolModule.ts

@@ -0,0 +1,27 @@
+import {
+  AreProofsEnabled,
+  ChildContainerProvider,
+  ConfigurableModule,
+  NoConfig,
+  noop,
+} from "@proto-kit/common";
+
+import { ProtocolEnvironment } from "./ProtocolEnvironment";
+
+export abstract class ProtocolModule<
+  Config = NoConfig,
+> extends ConfigurableModule<Config> {
+  public protocol?: ProtocolEnvironment;
+
+  public get areProofsEnabled(): AreProofsEnabled | undefined {
+    return this.protocol?.getAreProofsEnabled();
+  }
+
+  public create(childContainerProvider: ChildContainerProvider): void {
+    noop();
+  }
+
+  public async start() {
+    noop();
+  }
+}

package/src/protocol/ProvableBlockHook.ts

@@ -0,0 +1,19 @@
+import type { BlockProverState } from "../prover/block/BlockProver";
+import { NetworkState } from "../model/network/NetworkState";
+
+import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
+
+// Purpose is to build transition from -> to network state
+export abstract class ProvableBlockHook<
+  Config,
+> extends TransitioningProtocolModule<Config> {
+  public abstract beforeBlock(
+    networkState: NetworkState,
+    state: BlockProverState
+  ): Promise<NetworkState>;
+
+  public abstract afterBlock(
+    networkState: NetworkState,
+    state: BlockProverState
+  ): Promise<NetworkState>;
+}

package/src/protocol/ProvableTransactionHook.ts

@@ -0,0 +1,13 @@
+import { NoConfig } from "@proto-kit/common";
+
+import { BlockProverExecutionData } from "../prover/block/BlockProvable";
+
+import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
+
+export abstract class ProvableTransactionHook<
+  Config = NoConfig,
+> extends TransitioningProtocolModule<Config> {
+  public abstract onTransaction(
+    executionData: BlockProverExecutionData
+  ): Promise<void>;
+}

package/src/protocol/TransitioningProtocolModule.ts

@@ -0,0 +1,12 @@
+import { ProtocolModule } from "./ProtocolModule";
+
+/**
+ * TransitioningProtocolModule is a base interface that allows inheriting
+ * classes to use State and StateMap since it requires the implementation
+ * of a `name: string` property, which those classes need to function.
+ */
+export abstract class TransitioningProtocolModule<
+  Config,
+> extends ProtocolModule<Config> {
+  public name?: string;
+}

package/src/prover/block/BlockProvable.ts

@@ -0,0 +1,99 @@
+import {
+  Bool,
+  DynamicProof,
+  Field,
+  Proof,
+  Signature,
+  Struct,
+  Void,
+} from "o1js";
+import { WithZkProgrammable, CompilableModule } from "@proto-kit/common";
+
+import { StateTransitionProof } from "../statetransition/StateTransitionProvable";
+import { MethodPublicOutput } from "../../model/MethodPublicOutput";
+import { RuntimeTransaction } from "../../model/transaction/RuntimeTransaction";
+import { NetworkState } from "../../model/network/NetworkState";
+
+import { BlockHashMerkleTreeWitness } from "./accummulators/BlockHashMerkleTree";
+import { RuntimeVerificationKeyAttestation } from "./accummulators/RuntimeVerificationKeyTree";
+
+export class BlockProverPublicInput extends Struct({
+  transactionsHash: Field,
+  stateRoot: Field,
+  networkStateHash: Field,
+  blockHashRoot: Field,
+  eternalTransactionsHash: Field,
+  incomingMessagesHash: Field,
+  blockNumber: Field,
+}) {}
+
+export class BlockProverPublicOutput extends Struct({
+  transactionsHash: Field,
+  stateRoot: Field,
+  networkStateHash: Field,
+  blockHashRoot: Field,
+  eternalTransactionsHash: Field,
+  incomingMessagesHash: Field,
+  closed: Bool,
+  blockNumber: Field,
+}) {
+  public equals(input: BlockProverPublicInput, closed: Bool): Bool {
+    const output2 = BlockProverPublicOutput.toFields({
+      ...input,
+      closed,
+    });
+    const output1 = BlockProverPublicOutput.toFields(this);
+    return output1
+      .map((value1, index) => value1.equals(output2[index]))
+      .reduce((a, b) => a.and(b));
+  }
+}
+
+export type BlockProverProof = Proof<
+  BlockProverPublicInput,
+  BlockProverPublicOutput
+>;
+
+export class BlockProverExecutionData extends Struct({
+  transaction: RuntimeTransaction,
+  signature: Signature,
+  networkState: NetworkState,
+}) {}
+
+export class DynamicRuntimeProof extends DynamicProof<
+  Void,
+  MethodPublicOutput
+> {
+  static publicInputType = Void;
+
+  static publicOutputType = MethodPublicOutput;
+
+  // TODO this won't be 0 for proofs-as-args
+  static maxProofsVerified = 0 as const;
+}
+
+export interface BlockProvable
+  extends WithZkProgrammable<BlockProverPublicInput, BlockProverPublicOutput>,
+    CompilableModule {
+  proveTransaction: (
+    publicInput: BlockProverPublicInput,
+    stateProof: StateTransitionProof,
+    appProof: DynamicRuntimeProof,
+    executionData: BlockProverExecutionData,
+    verificationKeyAttestation: RuntimeVerificationKeyAttestation
+  ) => Promise<BlockProverPublicOutput>;
+
+  proveBlock: (
+    publicInput: BlockProverPublicInput,
+    networkState: NetworkState,
+    blockWitness: BlockHashMerkleTreeWitness,
+    // stateTransitionProof: StateTransitionProof,
+    transactionProof: BlockProverProof
+  ) => Promise<BlockProverPublicOutput>;
+
+  merge: (
+    publicInput: BlockProverPublicInput,
+    proof1: BlockProverProof,
+    proof2: BlockProverProof
+  ) => Promise<BlockProverPublicOutput>;
+}