@proto-kit/protocol 0.1.1-develop.457 → 0.1.1-develop.651

package/src/index.ts

@@ -1,22 +1,29 @@
-export * from "./blockmodules/AccountStateModule";
-export * from "./blockmodules/BlockHeightHook";
+export * from "./hooks/AccountStateHook";
+export * from "./hooks/BlockHeightHook";
 export * from "./utils/ProvableHashList";
+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/ProtocolTransaction";
+export * from "./model/transaction/SignedTransaction";
 export * from "./model/transaction/RuntimeTransaction";
-export * from "./utils/PrefixedProvableHashList.js";
+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/BlockTransactionPosition";
+export * from "./prover/block/accummulators/BlockHashMerkleTree";
 export * from "./prover/statetransition/StateTransitionProver";
 export * from "./prover/statetransition/StateTransitionProvable";
 export * from "./prover/statetransition/StateTransitionWitnessProvider";
-export * from "./model/MethodPublicOutput";
 export * from "./prover/statetransition/StateTransitionWitnessProviderReference";
 export * from "./protocol/Protocol";
 export * from "./protocol/ProtocolModule";
@@ -32,4 +39,15 @@ export * from "./state/StateMap";
 export * from "./state/StateService";
 export * from "./state/StateServiceProvider";
 export * from "./state/assert/assert";
+export * from "./settlement/contracts/SettlementSmartContract";
+export * from "./settlement/contracts/SettlementContractProtocolModule";
+export * from "./settlement/contracts/DispatchSmartContract";
+export * from "./settlement/contracts/DispatchContractProtocolModule";
+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

@@ -1,4 +1,4 @@
-import { Bool, Field, Struct } from "o1js";
+import { Bool, Field, Signature, Struct } from "o1js";
 
 /**
  * Public input used to link in-circuit execution with
@@ -9,4 +9,5 @@ export class MethodPublicOutput extends Struct({
   status: Bool,
   transactionHash: Field,
   networkStateHash: Field,
-}) {}
+  isMessage: Bool,
+}) {}

package/src/model/Option.ts

@@ -4,6 +4,7 @@ import {
   type FlexibleProvablePure,
   Poseidon,
   Provable,
+  ProvablePure,
   Struct,
 } from "o1js";
 
@@ -149,4 +150,19 @@ export class Option<Value> extends OptionBase {
       defaultValue
     );
   }
+
+  public toConstant() {
+    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/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

@@ -1,4 +1,4 @@
-import { Field, Struct } from "o1js";
+import { Bool, Field, ProvablePure, Struct } from "o1js";
 
 import { Option, ProvableOption } from "./Option";
 
@@ -44,7 +44,7 @@ export class StateTransition<Value> {
 
   public constructor(
     public path: Field,
-    public fromValue: Option<Field> | Option<Value>,
+    public fromValue: Option<Value>,
     public toValue: Option<Field> | Option<Value>
   ) {}
 
@@ -77,4 +77,12 @@ export class StateTransition<Value> {
       to: this.toValue.toJSON(),
     };
   }
+
+  public toConstant(): StateTransition<Value> {
+    return new StateTransition<Value>(
+      this.path.toConstant(),
+      this.fromValue.toConstant(),
+      this.toValue.toConstant()
+    );
+  }
 }

package/src/model/network/NetworkState.ts

@@ -1,21 +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));
+    return Poseidon.hash([
+      ...CurrentBlock.toFields(this.block),
+      ...PreviousBlock.toFields(this.previous),
+    ]);
   }
 
-  public static empty(){
+  public static empty() {
     return new NetworkState({
       block: {
         height: UInt64.zero,
       },
-    })
+      previous: {
+        rootHash: Field(RollupMerkleTree.EMPTY_ROOT)
+      }
+    });
   }
 }

package/src/model/transaction/RuntimeTransaction.ts

@@ -1,6 +1,14 @@
-import { Field, Poseidon, PublicKey, Struct, UInt64 } from "o1js";
-
-import { ProtocolTransaction } from "./ProtocolTransaction";
+import {
+  Bool,
+  Field,
+  Poseidon,
+  Provable,
+  PublicKey,
+  Struct,
+  UInt64,
+} from "o1js";
+import { PublicKeyOption, UInt64Option } from "./ValueOption";
+import { EMPTY_PUBLICKEY, EMPTY_PUBLICKEY_X } from "@proto-kit/common";
 
 /**
  * This struct is used to expose transaction information to the runtime method
@@ -9,30 +17,96 @@ import { ProtocolTransaction } from "./ProtocolTransaction";
  */
 export class RuntimeTransaction extends Struct({
   methodId: Field,
-  nonce: UInt64,
-  sender: PublicKey,
   argsHash: Field,
+  nonce: UInt64Option,
+  sender: PublicKeyOption,
 }) {
-  public static fromProtocolTransaction({
+  public static fromTransaction(input: {
+    methodId: Field;
+    argsHash: Field;
+    nonce: UInt64;
+    sender: PublicKey;
+  }) {
+    return new RuntimeTransaction({
+      methodId: input.methodId,
+      argsHash: input.argsHash,
+      nonce: UInt64Option.fromValue(input.nonce),
+      sender: PublicKeyOption.fromValue(input.sender),
+    });
+  }
+
+  public static fromMessage({
     methodId,
-    nonce,
-    sender,
     argsHash,
-  }: ProtocolTransaction): RuntimeTransaction {
+  }: {
+    methodId: Field;
+    argsHash: Field;
+  }) {
     return new RuntimeTransaction({
       methodId,
-      nonce,
-      sender,
       argsHash,
+      nonce: UInt64Option.none(UInt64.zero),
+      sender: PublicKeyOption.none(EMPTY_PUBLICKEY),
     });
   }
 
-  public hash(): Field {
-    return Poseidon.hash([
+  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.toFields(),
-      ...this.nonce.toFields(),
+      ...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,54 @@
+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 fromValue(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

@@ -19,51 +19,54 @@ import { StateService } from "../state/StateService";
 
 import { ProtocolModule } from "./ProtocolModule";
 import { ProvableTransactionHook } from "./ProvableTransactionHook";
-import { NoopTransactionHook } from "../blockmodules/NoopTransactionHook";
+import { NoopTransactionHook } from "../hooks/NoopTransactionHook";
 import { ProtocolEnvironment } from "./ProtocolEnvironment";
-import { AccountStateModule } from "../blockmodules/AccountStateModule";
+import { AccountStateHook } from "../hooks/AccountStateHook";
 import { ProvableBlockHook } from "./ProvableBlockHook";
-import { NoopBlockHook } from "../blockmodules/NoopBlockHook";
-import { BlockHeightHook } from "../blockmodules/BlockHeightHook";
+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";
 
-const PROTOCOL_INJECTION_TOKENS = {
+const PROTOCOL_INJECTION_TOKENS: Record<string, string> = {
   ProvableTransactionHook: "ProvableTransactionHook",
   ProvableBlockHook: "ProvableBlockHook",
+  ProvableSettlementHook: "ProvableSettlementHook",
 };
 
-export type GenericProtocolModuleRecord = ModulesRecord<
+export type ProtocolModulesRecord = ModulesRecord<
   TypedClass<ProtocolModule<unknown>>
 >;
 
-interface BlockProverType extends ProtocolModule, BlockProvable {}
+export interface BlockProverType extends ProtocolModule, BlockProvable {}
 
-interface StateTransitionProverType
+export interface StateTransitionProverType
   extends ProtocolModule,
     StateTransitionProvable {}
 
-export interface ProtocolCustomModulesRecord {
+export type MandatoryProtocolModulesRecord = {
   BlockProver: TypedClass<BlockProverType>;
   StateTransitionProver: TypedClass<StateTransitionProverType>;
-  AccountState: TypedClass<AccountStateModule>;
-}
-
-export interface ProtocolModulesRecord
-  extends GenericProtocolModuleRecord,
-    ProtocolCustomModulesRecord {}
+  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>
+export class Protocol<
+    Modules extends ProtocolModulesRecord & MandatoryProtocolModulesRecord
+  >
   extends ModuleContainer<Modules>
   implements ProtocolEnvironment
 {
-  // .from() to create Protocol
-  public static from<Modules extends ProtocolModulesRecord>(
-    modules: ProtocolDefinition<Modules>
-  ): TypedClass<Protocol<Modules>> {
+  public static from<
+    Modules extends ProtocolModulesRecord & MandatoryProtocolModulesRecord
+  >(modules: ProtocolDefinition<Modules>): TypedClass<Protocol<Modules>> {
     return class ScopedProtocol extends Protocol<Modules> {
       public constructor() {
         super(modules);
@@ -133,61 +136,51 @@ export class Protocol<Modules extends ProtocolModulesRecord>
 
     // Register the BlockModules seperately since we need to
     // inject them differently later
-    let atLeastOneTransactionHookRegistered = false;
-    let atLeastOneBlockHookRegistered = false;
-    Object.entries(this.definition.modules).forEach(([key, value]) => {
-      if (Object.prototype.isPrototypeOf.call(ProvableTransactionHook, value)) {
+    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(
-          PROTOCOL_INJECTION_TOKENS.ProvableTransactionHook,
+          abstractType.name,
           { useToken: key },
           { lifecycle: Lifecycle.ContainerScoped }
         );
-        atLeastOneTransactionHookRegistered = true;
-      }
-      if (Object.prototype.isPrototypeOf.call(ProvableBlockHook, value)) {
+      });
+      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(
-          PROTOCOL_INJECTION_TOKENS.ProvableBlockHook,
-          { useToken: key },
+          abstractType.name,
+          { useClass: defaultType },
           { lifecycle: Lifecycle.ContainerScoped }
         );
-        atLeastOneBlockHookRegistered = true;
       }
     });
-
-    // We need this so that tsyringe doesn't throw when no hooks are registered
-    if (!atLeastOneTransactionHookRegistered) {
-      this.container.register(
-        PROTOCOL_INJECTION_TOKENS.ProvableTransactionHook,
-        { useClass: NoopTransactionHook },
-        { lifecycle: Lifecycle.ContainerScoped }
-      );
-    }
-    if (!atLeastOneBlockHookRegistered) {
-      this.container.register(
-        PROTOCOL_INJECTION_TOKENS.ProvableBlockHook,
-        { useClass: NoopBlockHook },
-        { lifecycle: Lifecycle.ContainerScoped }
-      );
-    }
   }
 }
-
-export const VanillaProtocol = {
-  create() {
-    return VanillaProtocol.from({});
-  },
-
-  from<AdditonalModules extends GenericProtocolModuleRecord>(
-    additionalModules: AdditonalModules
-  ): TypedClass<Protocol<ProtocolModulesRecord>> {
-    return Protocol.from<ProtocolModulesRecord>({
-      modules: {
-        StateTransitionProver,
-        BlockProver,
-        AccountState: AccountStateModule,
-        BlockHeight: BlockHeightHook,
-        ...additionalModules,
-      },
-    });
-  },
-};

package/src/protocol/ProtocolModule.ts

@@ -1,8 +1,9 @@
 import {
   AreProofsEnabled,
   ChildContainerProvider,
-  ConfigurableModule, NoConfig,
-  noop
+  ConfigurableModule,
+  NoConfig,
+  noop,
 } from "@proto-kit/common";
 
 import { ProtocolEnvironment } from "./ProtocolEnvironment";

package/src/protocol/ProvableBlockHook.ts

@@ -3,20 +3,17 @@ import { NetworkState } from "../model/network/NetworkState";
 
 import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
 
-export interface BeforeBlockParameters {
-  state: BlockProverState;
-  networkState: NetworkState;
-}
-
-export interface AfterBlockParameters {
-  state: BlockProverState;
-  networkState: NetworkState;
-}
-
-// Purpose is to validate transition from -> to network state
+// Purpose is to build transition from -> to network state
 export abstract class ProvableBlockHook<
   Config
 > extends TransitioningProtocolModule<Config> {
-  public abstract beforeBlock(blockData: BeforeBlockParameters): NetworkState;
-  public abstract afterBlock(blockData: AfterBlockParameters): NetworkState;
+  public abstract beforeBlock(
+    networkState: NetworkState,
+    state: BlockProverState
+  ): NetworkState;
+
+  public abstract afterBlock(
+    networkState: NetworkState,
+    state: BlockProverState
+  ): NetworkState;
 }

package/src/protocol/ProvableTransactionHook.ts

@@ -1,7 +1,8 @@
+import { NoConfig } from "@proto-kit/common";
+
 import { BlockProverExecutionData } from "../prover/block/BlockProvable";
 
 import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
-import { NoConfig } from "@proto-kit/common";
 
 export abstract class ProvableTransactionHook<
   Config = NoConfig

package/src/protocol/TransitioningProtocolModule.ts

@@ -1,8 +1,9 @@
 import { ProtocolModule } from "./ProtocolModule";
 
 /**
- * A Protocolmodule that enables it's implementing module to access to
- * StateTransitions and state
+ * 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