@proto-kit/protocol 0.1.1-develop.191 → 0.1.1-develop.2024

package/src/settlement/contracts/BridgingSettlementContractModule.ts

@@ -0,0 +1,116 @@
+import { inject, injectable, injectAll } from "tsyringe";
+import {
+  ArtifactRecord,
+  ChildVerificationKeyService,
+  CompileRegistry,
+  log,
+} from "@proto-kit/common";
+
+import { BlockProvable } from "../../prover/block/BlockProvable";
+import {
+  ContractModule,
+  SmartContractClassFromInterface,
+} from "../ContractModule";
+import { ProvableSettlementHook } from "../modularity/ProvableSettlementHook";
+import { ContractArgsRegistry } from "../ContractArgsRegistry";
+
+import { DispatchContractArgs } from "./DispatchSmartContract";
+import {
+  BridgingSettlementContractType,
+  BridgingSettlementContract,
+  BridgingSettlementContractArgs,
+} from "./settlement/BridgingSettlementContract";
+import { BridgeContractArgs } from "./BridgeContract";
+import { DispatchContractProtocolModule } from "./DispatchContractProtocolModule";
+import { BridgeContractProtocolModule } from "./BridgeContractProtocolModule";
+import {
+  DEFAULT_ESCAPE_HATCH,
+  SettlementContractConfig,
+} from "./SettlementSmartContractModule";
+import { SettlementContract } from "./settlement/SettlementContract";
+
+@injectable()
+export class BridgingSettlementContractModule extends ContractModule<
+  BridgingSettlementContractType,
+  SettlementContractConfig
+> {
+  public constructor(
+    @injectAll("ProvableSettlementHook")
+    private readonly hooks: ProvableSettlementHook<unknown>[],
+    @inject("BlockProver")
+    private readonly blockProver: BlockProvable,
+    @inject("DispatchContract")
+    private readonly dispatchContractModule: DispatchContractProtocolModule,
+    @inject("BridgeContract")
+    private readonly bridgeContractModule: BridgeContractProtocolModule,
+    private readonly childVerificationKeyService: ChildVerificationKeyService,
+    private readonly argsRegistry: ContractArgsRegistry
+  ) {
+    super();
+  }
+
+  public contractFactory(): SmartContractClassFromInterface<BridgingSettlementContractType> {
+    const { hooks, config } = this;
+    const dispatchContract = this.dispatchContractModule.contractFactory();
+    const bridgeContract = this.bridgeContractModule.contractFactory();
+
+    const escapeHatchSlotsInterval =
+      config.escapeHatchSlotsInterval ?? DEFAULT_ESCAPE_HATCH;
+
+    this.argsRegistry.addArgs<BridgingSettlementContractArgs>(
+      "SettlementContract",
+      {
+        DispatchContract: dispatchContract,
+        hooks,
+        escapeHatchSlotsInterval,
+        BridgeContract: bridgeContract,
+        ChildVerificationKeyService: this.childVerificationKeyService,
+      }
+    );
+
+    // Ideally, we don't want to have this cyclic dependency, but we have it in the protocol,
+    // So it's logical that we can't avoid that here
+    this.argsRegistry.addArgs<BridgeContractArgs>("BridgeContract", {
+      SettlementContract: BridgingSettlementContract,
+    });
+    this.argsRegistry.addArgs<DispatchContractArgs>("DispatchContract", {
+      settlementContractClass: BridgingSettlementContract,
+    });
+
+    return BridgingSettlementContract;
+  }
+
+  public async compile(
+    registry: CompileRegistry
+  ): Promise<ArtifactRecord | undefined> {
+    // Dependencies
+    const bridgeArtifact = await this.bridgeContractModule.compile(registry);
+
+    await this.blockProver.compile(registry);
+
+    this.contractFactory();
+
+    // Init params
+    this.argsRegistry.addArgs<BridgingSettlementContractArgs>(
+      "SettlementContract",
+      {
+        BridgeContractVerificationKey:
+          bridgeArtifact.BridgeContract.verificationKey,
+      }
+    );
+
+    log.debug("Compiling Settlement Contract");
+
+    const artifact = await registry.forceProverExists(
+      async (reg) =>
+        await registry.compile(
+          BridgingSettlementContract,
+          SettlementContract.name
+        )
+    );
+
+    return {
+      SettlementSmartContract: artifact,
+    };
+  }
+}

package/src/settlement/contracts/DispatchContractProtocolModule.ts

@@ -0,0 +1,77 @@
+import { inject, injectable } from "tsyringe";
+import { PublicKey } from "o1js";
+import { CompileRegistry } from "@proto-kit/common";
+
+import { RuntimeLike, RuntimeMethodIdMapping } from "../../model/RuntimeLike";
+import {
+  ContractModule,
+  SmartContractClassFromInterface,
+} from "../ContractModule";
+import { ContractArgsRegistry } from "../ContractArgsRegistry";
+
+import {
+  DispatchSmartContract,
+  DispatchContractType,
+  DispatchContractArgs,
+} from "./DispatchSmartContract";
+
+export type DispatchContractConfig = {
+  incomingMessagesMethods: Record<string, `${string}.${string}`>;
+};
+
+@injectable()
+export class DispatchContractProtocolModule extends ContractModule<
+  DispatchContractType,
+  DispatchContractConfig
+> {
+  public constructor(
+    @inject("Runtime") private readonly runtime: RuntimeLike,
+    private readonly contractArgsRegistry: ContractArgsRegistry
+  ) {
+    super();
+  }
+
+  public eventsDefinition() {
+    return new DispatchSmartContract(PublicKey.empty<typeof PublicKey>())
+      .events;
+  }
+
+  private checkConfigIntegrity(
+    incomingMessagesMethods: Record<string, `${string}.${string}`>,
+    runtimeMethodIds: RuntimeMethodIdMapping
+  ) {
+    const missing = Object.values(incomingMessagesMethods).filter(
+      (method) => runtimeMethodIds[method] === undefined
+    );
+    if (missing.length > 0) {
+      throw new Error(
+        `Incoming messages config references a unknown methods: [${missing}]`
+      );
+    }
+  }
+
+  public contractFactory(): SmartContractClassFromInterface<DispatchContractType> {
+    const { incomingMessagesMethods } = this.config;
+    const methodIdMappings = this.runtime.methodIdResolver.methodIdMap();
+
+    this.checkConfigIntegrity(incomingMessagesMethods, methodIdMappings);
+
+    this.contractArgsRegistry.addArgs<DispatchContractArgs>(
+      "DispatchContract",
+      {
+        incomingMessagesPaths: incomingMessagesMethods,
+        methodIdMappings,
+      }
+    );
+
+    return DispatchSmartContract;
+  }
+
+  public async compile(registry: CompileRegistry) {
+    return {
+      DispatchSmartContract: await registry.forceProverExists(
+        async () => await registry.compile(DispatchSmartContract)
+      ),
+    };
+  }
+}

package/src/settlement/contracts/DispatchSmartContract.ts

@@ -0,0 +1,359 @@
+import {
+  AccountUpdate,
+  Bool,
+  DeployArgs,
+  Field,
+  method,
+  Poseidon,
+  Provable,
+  ProvableExtended,
+  PublicKey,
+  Reducer,
+  SmartContract,
+  State,
+  state,
+  TokenId,
+  UInt64,
+  Permissions,
+} from "o1js";
+import { InMemoryMerkleTreeStorage, TypedClass } from "@proto-kit/common";
+import { container } from "tsyringe";
+
+import { RuntimeMethodIdMapping } from "../../model/RuntimeLike";
+import { RuntimeTransaction } from "../../model/transaction/RuntimeTransaction";
+import {
+  MinaActions,
+  MinaEvents,
+} from "../../utils/MinaPrefixedProvableHashList";
+import { Deposit } from "../messages/Deposit";
+import {
+  ContractArgsRegistry,
+  NaiveObjectSchema,
+  StaticInitializationContract,
+} from "../ContractArgsRegistry";
+
+import type { BridgingSettlementContractType } from "./settlement/BridgingSettlementContract";
+import { TokenBridgeDeploymentAuth } from "./authorizations/TokenBridgeDeploymentAuth";
+import { UpdateMessagesHashAuth } from "./authorizations/UpdateMessagesHashAuth";
+import {
+  TokenBridgeAttestation,
+  TokenBridgeEntry,
+  TokenBridgeTree,
+  TokenBridgeTreeAddition,
+  TokenBridgeTreeWitness,
+} from "./TokenBridgeTree";
+
+export const ACTIONS_EMPTY_HASH = Reducer.initialActionState;
+
+export interface DispatchContractType {
+  events: {
+    "token-bridge-added": typeof TokenBridgeTreeAddition;
+  };
+
+  updateMessagesHash: (
+    executedMessagesHash: Field,
+    newPromisedMessagesHash: Field
+  ) => Promise<void>;
+  enableTokenDeposits: (
+    tokenId: Field,
+    bridgeContractAddress: PublicKey,
+    settlementContractAddress: PublicKey
+  ) => Promise<void>;
+
+  promisedMessagesHash: State<Field>;
+
+  deployAndInitialize: (
+    args: DeployArgs | undefined,
+    permissions: Permissions,
+    settlementContract: PublicKey
+  ) => Promise<void>;
+}
+
+const tokenBridgeRoot = new TokenBridgeTree(
+  new InMemoryMerkleTreeStorage()
+).getRoot();
+
+export interface DispatchContractArgs {
+  methodIdMappings: RuntimeMethodIdMapping;
+  incomingMessagesPaths: Record<string, `${string}.${string}`>;
+  settlementContractClass: TypedClass<BridgingSettlementContractType> &
+    typeof SmartContract;
+}
+
+export const DispatchContractArgsSchema: NaiveObjectSchema<DispatchContractArgs> =
+  {
+    incomingMessagesPaths: "Required",
+    methodIdMappings: "Required",
+    settlementContractClass: "Required",
+  };
+
+export abstract class DispatchSmartContractBase
+  extends SmartContract
+  implements StaticInitializationContract<DispatchContractArgs>
+{
+  events = {
+    "token-bridge-added": TokenBridgeTreeAddition,
+    // We need a placeholder event here, so that o1js internally adds a identifier to the
+    // emitted event-fields. That will lead to the o1js API being able to distinguish the
+    // TokenBridgeEvents from the manually emitted events for the incoming messages
+    "incoming-message-placeholder": Field,
+  };
+
+  abstract promisedMessagesHash: State<Field>;
+
+  abstract honoredMessagesHash: State<Field>;
+
+  abstract settlementContract: State<PublicKey>;
+
+  abstract tokenBridgeRoot: State<Field>;
+
+  abstract tokenBridgeCount: State<Field>;
+
+  getInitializationArgs(): DispatchContractArgs {
+    return container
+      .resolve(ContractArgsRegistry)
+      .getArgs("DispatchContract", DispatchContractArgsSchema);
+  }
+
+  protected updateMessagesHashBase(
+    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);
+
+    const args = this.getInitializationArgs();
+    const settlementContractAddress =
+      this.settlementContract.getAndRequireEquals();
+    const settlementContract = new args.settlementContractClass!(
+      settlementContractAddress
+    );
+
+    settlementContract.authorizationField.requireEquals(
+      new UpdateMessagesHashAuth({
+        target: this.address,
+        executedMessagesHash,
+        newPromisedMessagesHash,
+      }).hash()
+    );
+    this.approve(settlementContract.self);
+  }
+
+  protected initializeBase(settlementContract: PublicKey) {
+    this.promisedMessagesHash.set(ACTIONS_EMPTY_HASH);
+    this.honoredMessagesHash.set(ACTIONS_EMPTY_HASH);
+    this.settlementContract.set(settlementContract);
+  }
+
+  protected 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],
+    };
+
+    // Find event index of placeholder event that we can use for manual event dispatching
+    const eventIndex = Object.keys(this.events)
+      .sort()
+      .indexOf("incoming-message-placeholder");
+    if (eventIndex === -1) {
+      throw new Error("Unknown event type for placeholder event");
+    }
+    const paddedArgs = [Field(eventIndex), ...args];
+
+    const eventHash = MinaEvents.eventHash(paddedArgs);
+    this.self.body.events = {
+      hash: eventHash,
+      data: [paddedArgs],
+    };
+  }
+
+  protected async enableTokenDepositsBase(
+    tokenId: Field,
+    bridgeContractAddress: PublicKey,
+    // Witness it here, since o1js doesn't fetch this state correctly since
+    // its updated in a parent AU
+    settlementContractAddress: PublicKey
+    // treeWitness: TokenBridgeTreeWitness
+  ) {
+    this.settlementContract.requireEquals(settlementContractAddress);
+    const args = this.getInitializationArgs();
+    const settlementContract = new args.settlementContractClass!(
+      settlementContractAddress
+    );
+
+    // Append bridge address to the tree
+    // TODO This not concurrent and will fail if multiple users deploy bridges at the same time
+    const counter = this.tokenBridgeCount.getAndRequireEquals();
+    const root = this.tokenBridgeRoot.getAndRequireEquals();
+
+    const treeWitness = await Provable.witnessAsync(
+      TokenBridgeTreeWitness,
+      async () => {
+        const tree = await TokenBridgeTree.buildTreeFromEvents(this);
+        return tree.getWitness(counter.toBigInt());
+      }
+    );
+
+    treeWitness
+      .checkMembership(root, counter, Field(0))
+      .assertTrue("Bridge Tree Witness not valid");
+
+    const entry = new TokenBridgeEntry({
+      tokenId,
+      address: bridgeContractAddress,
+    });
+    const newRoot = treeWitness.calculateRoot(entry.hash());
+    this.tokenBridgeRoot.set(newRoot);
+    this.tokenBridgeCount.set(counter.add(1));
+
+    this.emitEvent(
+      "token-bridge-added",
+      new TokenBridgeTreeAddition({
+        index: counter,
+        value: entry,
+      })
+    );
+
+    // Authenticate call via callback
+    settlementContract.authorizationField.requireEquals(
+      new TokenBridgeDeploymentAuth({
+        target: this.address,
+        tokenId,
+        address: bridgeContractAddress,
+      }).hash()
+    );
+
+    this.approve(settlementContract.self);
+  }
+}
+
+export class DispatchSmartContract
+  extends DispatchSmartContractBase
+  implements DispatchContractType
+{
+  @state(Field) public promisedMessagesHash = State<Field>();
+
+  @state(Field) public honoredMessagesHash = State<Field>();
+
+  @state(PublicKey) public settlementContract = State<PublicKey>();
+
+  @state(Field) public tokenBridgeRoot = State<Field>(tokenBridgeRoot);
+
+  @state(Field) public tokenBridgeCount = State<Field>();
+
+  public async deployAndInitialize(
+    args: DeployArgs | undefined,
+    permissions: Permissions,
+    settlementContract: PublicKey
+  ): Promise<void> {
+    await super.deploy(args);
+
+    this.self.account.permissions.set(permissions);
+
+    this.initializeBase(settlementContract);
+  }
+
+  @method
+  public async enableTokenDeposits(
+    tokenId: Field,
+    bridgeContractAddress: PublicKey,
+    settlementContractAddress: PublicKey
+  ) {
+    await this.enableTokenDepositsBase(
+      tokenId,
+      bridgeContractAddress,
+      settlementContractAddress
+    );
+  }
+
+  @method
+  public async updateMessagesHash(
+    executedMessagesHash: Field,
+    newPromisedMessagesHash: Field
+  ) {
+    return this.updateMessagesHashBase(
+      executedMessagesHash,
+      newPromisedMessagesHash
+    );
+  }
+
+  @method
+  public async deposit(
+    amount: UInt64,
+    tokenId: Field,
+    bridgingContract: PublicKey,
+    bridgingContractAttestation: TokenBridgeAttestation,
+    l2Receiver: PublicKey
+  ) {
+    const childrenMayUseToken: AccountUpdate["body"]["mayUseToken"] = {
+      parentsOwnToken: Bool(false),
+      // MayUseToken has to be set only for custom tokens
+      inheritFromParent: tokenId.equals(TokenId.default).not(),
+    };
+
+    // Check that the bridgingContract parameter is valid => is in the offchain tree
+    const bridgeTreeRoot = this.tokenBridgeRoot.getAndRequireEquals();
+    const entry = new TokenBridgeEntry({
+      tokenId,
+      address: bridgingContract,
+    });
+
+    bridgingContractAttestation.witness
+      .checkMembership(
+        bridgeTreeRoot,
+        bridgingContractAttestation.index,
+        entry.hash()
+      )
+      .assertTrue("Bridging Contract Attestation not valid");
+
+    // Credit the amount to the settlement contract
+    const balanceAU = AccountUpdate.create(bridgingContract, tokenId);
+    balanceAU.balance.addInPlace(amount);
+    balanceAU.body.mayUseToken = childrenMayUseToken;
+    this.approve(balanceAU);
+
+    const action = new Deposit({
+      tokenId,
+      address: l2Receiver,
+      amount,
+    });
+
+    const { methodIdMappings, incomingMessagesPaths } =
+      this.getInitializationArgs();
+
+    const methodId = Field(
+      methodIdMappings[incomingMessagesPaths.deposit].methodId
+    ).toConstant();
+    this.dispatchMessage(methodId.toConstant(), action, Deposit);
+
+    this.self.body.mayUseToken = {
+      parentsOwnToken: tokenId.equals(TokenId.default).not(),
+      inheritFromParent: Bool(false),
+    };
+  }
+}

package/src/settlement/contracts/SettlementSmartContractModule.ts

@@ -0,0 +1,79 @@
+import { inject, injectable, injectAll } from "tsyringe";
+import {
+  ArtifactRecord,
+  ChildVerificationKeyService,
+  CompileRegistry,
+  log,
+} from "@proto-kit/common";
+
+import { BlockProvable } from "../../prover/block/BlockProvable";
+import {
+  ContractModule,
+  SmartContractClassFromInterface,
+} from "../ContractModule";
+import { ProvableSettlementHook } from "../modularity/ProvableSettlementHook";
+import { ContractArgsRegistry } from "../ContractArgsRegistry";
+
+import {
+  SettlementContractArgs,
+  SettlementContractType,
+} from "./settlement/SettlementBase";
+import { SettlementContract } from "./settlement/SettlementContract";
+
+export type SettlementContractConfig = {
+  escapeHatchSlotsInterval?: number;
+};
+
+// 24 hours
+export const DEFAULT_ESCAPE_HATCH = (60 / 3) * 24;
+
+@injectable()
+export class SettlementSmartContractModule extends ContractModule<
+  SettlementContractType,
+  SettlementContractConfig
+> {
+  public constructor(
+    @injectAll("ProvableSettlementHook")
+    private readonly hooks: ProvableSettlementHook<unknown>[],
+    @inject("BlockProver")
+    private readonly blockProver: BlockProvable,
+    private readonly childVerificationKeyService: ChildVerificationKeyService,
+    private readonly argsRegistry: ContractArgsRegistry
+  ) {
+    super();
+  }
+
+  public contractFactory(): SmartContractClassFromInterface<SettlementContractType> {
+    const { hooks, config } = this;
+
+    const escapeHatchSlotsInterval =
+      config.escapeHatchSlotsInterval ?? DEFAULT_ESCAPE_HATCH;
+
+    this.argsRegistry.addArgs<SettlementContractArgs>("SettlementContract", {
+      hooks,
+      escapeHatchSlotsInterval,
+      ChildVerificationKeyService: this.childVerificationKeyService,
+    });
+
+    return SettlementContract;
+  }
+
+  public async compile(
+    registry: CompileRegistry
+  ): Promise<ArtifactRecord | undefined> {
+    // Dependencies
+    await this.blockProver.compile(registry);
+
+    this.contractFactory();
+
+    log.debug("Compiling Settlement Contract");
+
+    const artifact = await registry.forceProverExists(
+      async (reg) => await registry.compile(SettlementContract)
+    );
+
+    return {
+      SettlementSmartContract: artifact,
+    };
+  }
+}

package/src/settlement/contracts/TokenBridgeTree.ts

@@ -0,0 +1,73 @@
+import {
+  createMerkleTree,
+  InMemoryMerkleTreeStorage,
+  log,
+} from "@proto-kit/common";
+import { Field, Poseidon, PublicKey, SmartContract, Struct } from "o1js";
+
+/**
+ * Merkle tree that contains all the deployed token bridges as a mapping of
+ * tokenId => PublicKey
+ *
+ * It should be used as an append-only tree with incremental indizes - this allows
+ * us to reduce the height of it
+ */
+export class TokenBridgeTree extends createMerkleTree(256) {
+  public indizes: Record<string, bigint> = {};
+
+  /**
+   * Initializes and fills the tree based on all on-chain events that have been
+   * emitted by every emit
+   */
+  public static async buildTreeFromEvents(
+    contract: SmartContract & {
+      events: { "token-bridge-added": typeof TokenBridgeTreeAddition };
+    }
+  ) {
+    const events = await contract.fetchEvents();
+
+    log.debug(`Found ${events.length} token bridge add events`);
+
+    const tree = new TokenBridgeTree(new InMemoryMerkleTreeStorage());
+    const indizes: Record<string, bigint> = {};
+
+    events.forEach(({ type, event }) => {
+      if (type === "token-bridge-added") {
+        const addition =
+          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+          event.data as unknown as TokenBridgeTreeAddition;
+
+        tree.setLeaf(addition.index.toBigInt(), addition.value.hash());
+
+        indizes[addition.value.tokenId.toString()] = addition.index.toBigInt();
+      }
+    });
+    tree.indizes = indizes;
+    return tree;
+  }
+
+  public getIndex(tokenId: Field): bigint {
+    return this.indizes[tokenId.toString()];
+  }
+}
+
+export class TokenBridgeTreeWitness extends TokenBridgeTree.WITNESS {}
+
+export class TokenBridgeEntry extends Struct({
+  address: PublicKey,
+  tokenId: Field,
+}) {
+  public hash() {
+    return Poseidon.hash(TokenBridgeEntry.toFields(this));
+  }
+}
+
+export class TokenBridgeAttestation extends Struct({
+  witness: TokenBridgeTreeWitness,
+  index: Field,
+}) {}
+
+export class TokenBridgeTreeAddition extends Struct({
+  index: Field,
+  value: TokenBridgeEntry,
+}) {}