zkcloudworker 0.18.1 → 0.18.4

package/src/mina/storage/pinata.ts

@@ -0,0 +1,52 @@
+export async function pinJSON(params: {
+  data: string | object;
+  name?: string;
+  keyvalues?: object;
+  auth?: string;
+}): Promise<string | undefined> {
+  const {
+    data,
+    name = "data.json",
+    keyvalues = [{ key: "library", value: "zkcloudworker" }],
+  } = params;
+  const auth =
+    params.auth ??
+    process.env.PINATA_JWT ??
+    process.env.NEXT_PUBLIC_PINATA_JWT ??
+    process.env.REACT_APP_PINATA_JWT;
+
+  try {
+    const pinataData = {
+      pinataOptions: {
+        cidVersion: 1,
+      },
+      pinataMetadata: {
+        name,
+        keyvalues,
+      },
+      pinataContent: data,
+    };
+
+    const res = await fetch("https://api.pinata.cloud/pinning/pinJSONToIPFS", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: "Bearer " + auth,
+      },
+      body: JSON.stringify(pinataData),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Pinata error: status: ${res.status} ${res.statusText}`);
+    }
+
+    const responseData = await res.json();
+    console.log("saveToIPFS result:", responseData);
+    return (
+      responseData as unknown as { IpfsHash: string | undefined } | undefined
+    )?.IpfsHash;
+  } catch (error: any) {
+    console.error("saveToIPFS error:", error?.message);
+    return undefined;
+  }
+}

package/src/mina/storage/storage.ts

@@ -0,0 +1,55 @@
+import { Field, Bool, Struct, Encoding, Provable } from "o1js";
+
+/**
+ * Represents the off-chain storage information,
+ * such as an IPFS hash.
+ */
+export class Storage extends Struct({
+  url: Provable.Array(Field, 2),
+}) {
+  constructor(value: { url: [Field, Field] }) {
+    super(value);
+  }
+
+  /**
+   * Asserts that two Storage instances are equal.
+   * @param a The first Storage instance.
+   * @param b The second Storage instance.
+   */
+  static assertEquals(a: Storage, b: Storage) {
+    a.url[0].assertEquals(b.url[0]);
+    a.url[1].assertEquals(b.url[1]);
+  }
+
+  /**
+   * Checks if two Storage instances are equal.
+   * @param a The first Storage instance.
+   * @param b The second Storage instance.
+   * @returns A Bool indicating whether the two instances are equal.
+   */
+  static equals(a: Storage, b: Storage): Bool {
+    return a.url[0].equals(b.url[0]).and(a.url[1].equals(b.url[1]));
+  }
+
+  /**
+   * Creates a Storage instance from a string.
+   * @param url The string representing the storage URL.
+   * @returns A new Storage instance.
+   */
+  static fromString(url: string): Storage {
+    const fields = Encoding.stringToFields(url);
+    if (fields.length !== 2) throw new Error("Invalid string length");
+    return new Storage({ url: [fields[0], fields[1]] });
+  }
+
+  /**
+   * Converts the Storage instance to a string.
+   * @returns The string representation of the storage URL.
+   */
+  toString(): string {
+    if (this.url[0].toBigInt() === 0n && this.url[1].toBigInt() === 0n) {
+      throw new Error("Invalid string");
+    }
+    return Encoding.stringFromFields([this.url[0], this.url[1]]);
+  }
+}

package/src/mina/token/FungibleToken.ts

@@ -0,0 +1,316 @@
+import {
+  AccountUpdate,
+  AccountUpdateForest,
+  assert,
+  Bool,
+  DeployArgs,
+  Field,
+  Int64,
+  method,
+  Permissions,
+  Provable,
+  PublicKey,
+  State,
+  state,
+  Struct,
+  TokenContract,
+  Types,
+  UInt64,
+  UInt8,
+  VerificationKey,
+} from "o1js";
+import {
+  FungibleTokenAdmin,
+  FungibleTokenAdminBase,
+} from "./FungibleTokenAdmin.js";
+
+interface FungibleTokenDeployProps extends Exclude<DeployArgs, undefined> {
+  /** The token symbol. */
+  symbol: string;
+  /** A source code reference, which is placed within the `zkappUri` of the contract account.
+   * Typically a link to a file on github. */
+  src: string;
+}
+
+export const FungibleTokenErrors = {
+  noAdminKey: "could not fetch admin contract key",
+  noPermissionToChangeAdmin: "Not allowed to change admin contract",
+  tokenPaused: "Token is currently paused",
+  noPermissionToMint: "Not allowed to mint tokens",
+  noPermissionToPause: "Not allowed to pause token",
+  noPermissionToResume: "Not allowed to resume token",
+  noTransferFromCirculation: "Can't transfer to/from the circulation account",
+  noPermissionChangeAllowed:
+    "Can't change permissions for access or receive on token accounts",
+  flashMinting:
+    "Flash-minting or unbalanced transaction detected. Please make sure that your transaction is balanced, and that your `AccountUpdate`s are ordered properly, so that tokens are not received before they are sent.",
+  unbalancedTransaction: "Transaction is unbalanced",
+};
+
+export class FungibleToken extends TokenContract {
+  @state(UInt8)
+  decimals = State<UInt8>();
+  @state(PublicKey)
+  admin = State<PublicKey>();
+  @state(Bool)
+  paused = State<Bool>();
+
+  // This defines the type of the contract that is used to control access to administrative actions.
+  // If you want to have a custom contract, overwrite this by setting FungibleToken.AdminContract to
+  // your own implementation of FungibleTokenAdminBase.
+  static AdminContract: new (...args: any) => FungibleTokenAdminBase =
+    FungibleTokenAdmin;
+
+  readonly events = {
+    SetAdmin: SetAdminEvent,
+    Pause: PauseEvent,
+    Mint: MintEvent,
+    Burn: BurnEvent,
+    BalanceChange: BalanceChangeEvent,
+  };
+
+  async deploy(props: FungibleTokenDeployProps) {
+    await super.deploy(props);
+    this.paused.set(Bool(true));
+    this.account.zkappUri.set(props.src);
+    this.account.tokenSymbol.set(props.symbol);
+
+    this.account.permissions.set({
+      ...Permissions.default(),
+      setVerificationKey:
+        Permissions.VerificationKey.impossibleDuringCurrentVersion(),
+      setPermissions: Permissions.impossible(),
+      access: Permissions.proof(),
+    });
+  }
+
+  /** Update the verification key.
+   * Note that because we have set the permissions for setting the verification key to `impossibleDuringCurrentVersion()`, this will only be possible in case of a protocol update that requires an update.
+   */
+  @method
+  async updateVerificationKey(vk: VerificationKey) {
+    this.account.verificationKey.set(vk);
+  }
+
+  /** Initializes the account for tracking total circulation.
+   * @argument {PublicKey} admin - public key where the admin contract is deployed
+   * @argument {UInt8} decimals - number of decimals for the token
+   * @argument {Bool} startPaused - if set to `Bool(true), the contract will start in a mode where token minting and transfers are paused. This should be used for non-atomic deployments
+   */
+  @method
+  async initialize(admin: PublicKey, decimals: UInt8, startPaused: Bool) {
+    this.account.provedState.requireEquals(Bool(false));
+
+    this.admin.set(admin);
+    this.decimals.set(decimals);
+    this.paused.set(Bool(false));
+
+    this.paused.set(startPaused);
+
+    const accountUpdate = AccountUpdate.createSigned(
+      this.address,
+      this.deriveTokenId()
+    );
+    let permissions = Permissions.default();
+    // This is necessary in order to allow token holders to burn.
+    permissions.send = Permissions.none();
+    permissions.setPermissions = Permissions.impossible();
+    accountUpdate.account.permissions.set(permissions);
+  }
+
+  public async getAdminContract(): Promise<FungibleTokenAdminBase> {
+    const admin = await Provable.witnessAsync(PublicKey, async () => {
+      let pk = await this.admin.fetch();
+      assert(pk !== undefined, FungibleTokenErrors.noAdminKey);
+      return pk;
+    });
+    this.admin.requireEquals(admin);
+    return new FungibleToken.AdminContract(admin);
+  }
+
+  @method
+  async setAdmin(admin: PublicKey) {
+    const adminContract = await this.getAdminContract();
+    const canChangeAdmin = await adminContract.canChangeAdmin(admin);
+    canChangeAdmin.assertTrue(FungibleTokenErrors.noPermissionToChangeAdmin);
+    this.admin.set(admin);
+    this.emitEvent("SetAdmin", new SetAdminEvent({ adminKey: admin }));
+  }
+
+  @method.returns(AccountUpdate)
+  async mint(recipient: PublicKey, amount: UInt64): Promise<AccountUpdate> {
+    this.paused
+      .getAndRequireEquals()
+      .assertFalse(FungibleTokenErrors.tokenPaused);
+    const accountUpdate = this.internal.mint({ address: recipient, amount });
+    const adminContract = await this.getAdminContract();
+    const canMint = await adminContract.canMint(accountUpdate);
+    canMint.assertTrue(FungibleTokenErrors.noPermissionToMint);
+    recipient
+      .equals(this.address)
+      .assertFalse(FungibleTokenErrors.noTransferFromCirculation);
+    this.approve(accountUpdate);
+    this.emitEvent("Mint", new MintEvent({ recipient, amount }));
+    const circulationUpdate = AccountUpdate.create(
+      this.address,
+      this.deriveTokenId()
+    );
+    circulationUpdate.balanceChange = Int64.fromUnsigned(amount);
+    return accountUpdate;
+  }
+
+  @method.returns(AccountUpdate)
+  async burn(from: PublicKey, amount: UInt64): Promise<AccountUpdate> {
+    this.paused
+      .getAndRequireEquals()
+      .assertFalse(FungibleTokenErrors.tokenPaused);
+    const accountUpdate = this.internal.burn({ address: from, amount });
+    const circulationUpdate = AccountUpdate.create(
+      this.address,
+      this.deriveTokenId()
+    );
+    from
+      .equals(this.address)
+      .assertFalse(FungibleTokenErrors.noTransferFromCirculation);
+    circulationUpdate.balanceChange = Int64.fromUnsigned(amount).neg();
+    this.emitEvent("Burn", new BurnEvent({ from, amount }));
+    return accountUpdate;
+  }
+
+  @method
+  async pause() {
+    const adminContract = await this.getAdminContract();
+    const canPause = await adminContract.canPause();
+    canPause.assertTrue(FungibleTokenErrors.noPermissionToPause);
+    this.paused.set(Bool(true));
+    this.emitEvent("Pause", new PauseEvent({ isPaused: Bool(true) }));
+  }
+
+  @method
+  async resume() {
+    const adminContract = await this.getAdminContract();
+    const canResume = await adminContract.canResume();
+    canResume.assertTrue(FungibleTokenErrors.noPermissionToResume);
+    this.paused.set(Bool(false));
+    this.emitEvent("Pause", new PauseEvent({ isPaused: Bool(false) }));
+  }
+
+  @method
+  async transfer(from: PublicKey, to: PublicKey, amount: UInt64) {
+    this.paused
+      .getAndRequireEquals()
+      .assertFalse(FungibleTokenErrors.tokenPaused);
+    from
+      .equals(this.address)
+      .assertFalse(FungibleTokenErrors.noTransferFromCirculation);
+    to.equals(this.address).assertFalse(
+      FungibleTokenErrors.noTransferFromCirculation
+    );
+    this.internal.send({ from, to, amount });
+  }
+
+  private checkPermissionsUpdate(update: AccountUpdate) {
+    let permissions = update.update.permissions;
+
+    let { access, receive } = permissions.value;
+    let accessIsNone = Provable.equal(
+      Types.AuthRequired,
+      access,
+      Permissions.none()
+    );
+    let receiveIsNone = Provable.equal(
+      Types.AuthRequired,
+      receive,
+      Permissions.none()
+    );
+    let updateAllowed = accessIsNone.and(receiveIsNone);
+
+    assert(
+      updateAllowed.or(permissions.isSome.not()),
+      FungibleTokenErrors.noPermissionChangeAllowed
+    );
+  }
+
+  /** Approve `AccountUpdate`s that have been created outside of the token contract.
+   *
+   * @argument {AccountUpdateForest} updates - The `AccountUpdate`s to approve. Note that the forest size is limited by the base token contract, @see TokenContractV2.MAX_ACCOUNT_UPDATES The current limit is 9.
+   */
+  @method
+  async approveBase(updates: AccountUpdateForest): Promise<void> {
+    this.paused
+      .getAndRequireEquals()
+      .assertFalse(FungibleTokenErrors.tokenPaused);
+    let totalBalance = Int64.from(0);
+    this.forEachUpdate(updates, (update, usesToken) => {
+      // Make sure that the account permissions are not changed
+      this.checkPermissionsUpdate(update);
+      this.emitEventIf(
+        usesToken,
+        "BalanceChange",
+        new BalanceChangeEvent({
+          address: update.publicKey,
+          amount: update.balanceChange,
+        })
+      );
+      // Don't allow transfers to/from the account that's tracking circulation
+      update.publicKey
+        .equals(this.address)
+        .and(usesToken)
+        .assertFalse(FungibleTokenErrors.noTransferFromCirculation);
+      totalBalance = Provable.if(
+        usesToken,
+        totalBalance.add(update.balanceChange),
+        totalBalance
+      );
+      totalBalance.isPositive().assertFalse(FungibleTokenErrors.flashMinting);
+    });
+    totalBalance.assertEquals(
+      Int64.zero,
+      FungibleTokenErrors.unbalancedTransaction
+    );
+  }
+
+  @method.returns(UInt64)
+  async getBalanceOf(address: PublicKey): Promise<UInt64> {
+    const account = AccountUpdate.create(address, this.deriveTokenId()).account;
+    const balance = account.balance.get();
+    account.balance.requireEquals(balance);
+    return balance;
+  }
+
+  /** Reports the current circulating supply
+   * This does take into account currently unreduced actions.
+   */
+  async getCirculating(): Promise<UInt64> {
+    let circulating = await this.getBalanceOf(this.address);
+    return circulating;
+  }
+
+  @method.returns(UInt8)
+  async getDecimals(): Promise<UInt8> {
+    return this.decimals.getAndRequireEquals();
+  }
+}
+
+export class SetAdminEvent extends Struct({
+  adminKey: PublicKey,
+}) {}
+
+export class PauseEvent extends Struct({
+  isPaused: Bool,
+}) {}
+
+export class MintEvent extends Struct({
+  recipient: PublicKey,
+  amount: UInt64,
+}) {}
+
+export class BurnEvent extends Struct({
+  from: PublicKey,
+  amount: UInt64,
+}) {}
+
+export class BalanceChangeEvent extends Struct({
+  address: PublicKey,
+  amount: Int64,
+}) {}

package/src/mina/token/FungibleTokenAdmin.ts

@@ -0,0 +1,95 @@
+import {
+  AccountUpdate,
+  assert,
+  Bool,
+  DeployArgs,
+  method,
+  Permissions,
+  Provable,
+  PublicKey,
+  SmartContract,
+  State,
+  state,
+  VerificationKey,
+} from "o1js";
+
+export type FungibleTokenAdminBase = SmartContract & {
+  canMint(accountUpdate: AccountUpdate): Promise<Bool>;
+  canChangeAdmin(admin: PublicKey): Promise<Bool>;
+  canPause(): Promise<Bool>;
+  canResume(): Promise<Bool>;
+};
+
+export interface FungibleTokenAdminDeployProps
+  extends Exclude<DeployArgs, undefined> {
+  adminPublicKey: PublicKey;
+}
+
+/** A contract that grants permissions for administrative actions on a token.
+ *
+ * We separate this out into a dedicated contract. That way, when issuing a token, a user can
+ * specify their own rules for administrative actions, without changing the token contract itself.
+ *
+ * The advantage is that third party applications that only use the token in a non-privileged way
+ * can integrate against the unchanged token contract.
+ */
+export class FungibleTokenAdmin
+  extends SmartContract
+  implements FungibleTokenAdminBase
+{
+  @state(PublicKey)
+  private adminPublicKey = State<PublicKey>();
+
+  async deploy(props: FungibleTokenAdminDeployProps) {
+    await super.deploy(props);
+    this.adminPublicKey.set(props.adminPublicKey);
+    this.account.permissions.set({
+      ...Permissions.default(),
+      setVerificationKey:
+        Permissions.VerificationKey.impossibleDuringCurrentVersion(),
+      setPermissions: Permissions.impossible(),
+    });
+  }
+
+  /** Update the verification key.
+   * Note that because we have set the permissions for setting the verification key to `impossibleDuringCurrentVersion()`, this will only be possible in case of a protocol update that requires an update.
+   */
+  @method
+  async updateVerificationKey(vk: VerificationKey) {
+    this.account.verificationKey.set(vk);
+  }
+
+  private async ensureAdminSignature() {
+    const admin = await Provable.witnessAsync(PublicKey, async () => {
+      let pk = await this.adminPublicKey.fetch();
+      assert(pk !== undefined, "could not fetch admin public key");
+      return pk;
+    });
+    this.adminPublicKey.requireEquals(admin);
+    return AccountUpdate.createSigned(admin);
+  }
+
+  @method.returns(Bool)
+  public async canMint(_accountUpdate: AccountUpdate) {
+    await this.ensureAdminSignature();
+    return Bool(true);
+  }
+
+  @method.returns(Bool)
+  public async canChangeAdmin(_admin: PublicKey) {
+    await this.ensureAdminSignature();
+    return Bool(true);
+  }
+
+  @method.returns(Bool)
+  public async canPause(): Promise<Bool> {
+    await this.ensureAdminSignature();
+    return Bool(true);
+  }
+
+  @method.returns(Bool)
+  public async canResume(): Promise<Bool> {
+    await this.ensureAdminSignature();
+    return Bool(true);
+  }
+}

package/src/mina/token/api.ts

@@ -0,0 +1,182 @@
+import { blockchain, Cloud, JobStatus } from "../../cloud/index.js";
+import { zkCloudWorkerClient } from "../api/api.js";
+import { zkCloudWorker } from "../../cloud/worker/index.js";
+
+export interface FungibleTokenDeployParams {
+  txType: "deploy";
+  tokenAddress: string;
+  adminContractAddress: string;
+  senderAddress: string;
+  chain: string;
+  symbol: string;
+  uri: string;
+  serializedTransaction: string;
+  signedData: string;
+  sendTransaction: boolean;
+  developerAddress?: string;
+  developerFee?: number;
+}
+
+export type FungibleTokenTransactionType =
+  | "mint"
+  | "transfer"
+  | "bid"
+  | "offer"
+  | "buy"
+  | "sell"
+  | "withdrawBid"
+  | "withdrawOffer";
+export interface FungibleTokenTransactionParams {
+  txType: FungibleTokenTransactionType;
+  tokenAddress: string;
+  chain: string;
+  serializedTransaction: string;
+  signedData: string;
+  from: string;
+  to: string;
+  amount: number;
+  price?: number;
+  sendTransaction: boolean;
+  developerAddress?: string;
+  developerFee?: number;
+  symbol?: string;
+}
+
+export interface FungibleTokenJobResult {
+  success: boolean;
+  jobStatus?: JobStatus;
+  tx?: string;
+  hash?: string;
+  error?: string;
+}
+
+export class TokenAPI {
+  readonly client: zkCloudWorkerClient;
+
+  constructor(params: {
+    jwt: string;
+    zkcloudworker?: (cloud: Cloud) => Promise<zkCloudWorker>;
+    chain: blockchain;
+  }) {
+    const { jwt, zkcloudworker, chain } = params;
+    if (jwt === undefined) throw new Error("jwt is undefined");
+
+    this.client = new zkCloudWorkerClient({
+      jwt,
+      chain,
+      zkcloudworker,
+    });
+  }
+
+  async sendDeployTransaction(
+    params: FungibleTokenDeployParams
+  ): Promise<string | undefined> {
+    const { symbol } = params;
+
+    const transaction = JSON.stringify(params, null, 2);
+
+    const answer = await this.client.execute({
+      developer: "DFST",
+      repo: "token-launchpad",
+      transactions: [transaction],
+      task: "deploy",
+      args: JSON.stringify({ tokenAddress: params.tokenAddress }),
+      metadata: `deploy token ${symbol}`,
+    });
+
+    const jobId = answer.jobId;
+    if (jobId === undefined)
+      console.error("Deploy Job ID is undefined", { answer, symbol });
+    return jobId;
+  }
+
+  async sendTransaction(
+    params: FungibleTokenTransactionParams
+  ): Promise<string | undefined> {
+    const { txType, symbol } = params;
+
+    const transaction = JSON.stringify(params, null, 2);
+
+    const answer = await this.client.execute({
+      developer: "DFST",
+      repo: "token-launchpad",
+      transactions: [transaction],
+      task: txType,
+      args: JSON.stringify({ tokenAddress: params.tokenAddress }),
+      metadata: `${txType} token${symbol ? ` ${symbol}` : ""}`,
+    });
+    const jobId = answer.jobId;
+    if (jobId === undefined)
+      console.error("Job ID is undefined", { answer, txType, symbol });
+    return jobId;
+  }
+
+  // Warning: this function will block the thread until the job is done and will print logs to the console
+  // Do not use it in "use server" functions, use getResult instead
+  async waitForJobResult(params: {
+    jobId: string;
+    maxAttempts?: number;
+    interval?: number;
+    maxErrors?: number;
+    printLogs?: boolean;
+  }): Promise<string | undefined> {
+    const deployResult = await this.client.waitForJobResult(params);
+    console.log(
+      "waitForJobResult result:",
+      deployResult?.result?.result?.slice(0, 50)
+    );
+    return deployResult?.result?.result ?? "error";
+  }
+
+  async getResult(jobId: string): Promise<FungibleTokenJobResult> {
+    try {
+      const callResult = await this.client.jobResult({ jobId });
+      const jobStatus: JobStatus | undefined =
+        callResult?.success === true
+          ? callResult?.result?.jobStatus
+          : undefined;
+      if (!callResult.success) {
+        return {
+          success: false,
+          error: callResult?.error,
+          jobStatus,
+        };
+      }
+      const jobResult = callResult.result?.result;
+      if (callResult.error)
+        return {
+          success: false,
+          error: callResult.error,
+          jobStatus,
+        };
+      if (!jobResult) return { success: true, jobStatus };
+
+      if (jobResult.toLowerCase().startsWith("error"))
+        return {
+          success: false,
+          error: jobResult,
+          jobStatus,
+        };
+
+      try {
+        const { success, tx, hash, error } = JSON.parse(jobResult);
+        if (success === undefined)
+          return {
+            success: false,
+            tx,
+            hash,
+            error,
+            jobStatus,
+          };
+        return { success, tx, hash, error, jobStatus };
+      } catch (e) {
+        return {
+          success: false,
+          error: `Error parsing job result: ${jobResult}`,
+        };
+      }
+    } catch (e) {
+      return { success: false, error: `Error getting job result: ${e}` };
+    }
+  }
+}

package/src/mina/token/index.ts

@@ -0,0 +1,5 @@
+export * from "./FungibleToken.js";
+export * from "./FungibleTokenAdmin.js";
+export * from "./api.js";
+export * from "./vk.js";
+export * from "./whitelist.js";