@silvana-one/nft 0.1.0

package/src/contracts/index.ts

@@ -0,0 +1,3 @@
+export * from "./collection.js";
+export * from "./nft.js";
+export * from "./admin.js";

package/src/contracts/nft.ts

@@ -0,0 +1,344 @@
+import {
+  Field,
+  PublicKey,
+  Bool,
+  SmartContract,
+  method,
+  state,
+  State,
+  VerificationKey,
+} from "o1js";
+import { Storage } from "@silvana-one/storage";
+import {
+  NFTData,
+  NFTDataPacked,
+  NFTState,
+  NFTImmutableState,
+  UpdateEvent,
+  TransferExtendedParams,
+  UpgradeVerificationKeyEvent,
+  PauseEvent,
+  OwnershipChangeEvent,
+  UpgradeVerificationKeyData,
+  NFTStateStruct,
+  NFTTransactionContext,
+} from "../interfaces/index.js";
+
+export { NFT };
+
+const NftErrors = {
+  cannotChangeMetadataVerificationKeyHash:
+    "Cannot change metadata verification key hash",
+  cannotChangeOwner: "Cannot change owner",
+  cannotChangeStorage: "Cannot change storage",
+  cannotChangePauseState: "Cannot change pause state",
+  noPermissionToPause: "No permission to pause",
+  nftAlreadyPaused: "NFT is already paused",
+  nftIsNotPaused: "NFT is not paused",
+  nftIsPaused: "NFT is paused",
+  cannotChangeName: "Cannot change name",
+  cannotChangeMetadata: "Cannot change metadata",
+  noMetadataVerificationKey: "No metadata verification key",
+};
+
+/**
+ * The NFT Contract represents an individual NFT within a collection.
+ *
+ * It manages the state and behavior of a single NFT, including ownership, metadata,
+ * storage, pricing, and permissions. The contract provides functionality for updating
+ * NFT properties with proofs and permissions, transferring ownership, selling and buying NFTs,
+ * upgrading the verification key, and pausing or resuming the NFT.
+ */
+class NFT extends SmartContract {
+  /** The name of the NFT (`Field`). */
+  @state(Field) name = State<Field>();
+
+  /** The metadata associated with the NFT (`Field`). */
+  @state(Field) metadata = State<Field>();
+
+  /** Holds off-chain storage information, e.g., IPFS hash (`Storage`). */
+  @state(Storage) storage = State<Storage>();
+
+  /** A packed field containing additional NFT data and flags (`Field`). */
+  @state(NFTDataPacked) packedData = State<NFTDataPacked>();
+
+  /** The hash of the verification key used for metadata proofs (`Field`). */
+  @state(Field) metadataVerificationKeyHash = State<Field>();
+
+  /** Events emitted by the NFT contract. */
+  events = {
+    update: UpdateEvent,
+    transfer: OwnershipChangeEvent,
+    approve: PublicKey,
+    upgradeVerificationKey: UpgradeVerificationKeyEvent,
+    pause: PauseEvent,
+    resume: PauseEvent,
+  };
+
+  @method.returns(NFTStateStruct)
+  async getState(): Promise<NFTStateStruct> {
+    const name = this.name.getAndRequireEquals();
+    const metadata = this.metadata.getAndRequireEquals();
+    const storage = this.storage.getAndRequireEquals();
+    const packedData = this.packedData.getAndRequireEquals();
+    const metadataVerificationKeyHash =
+      this.metadataVerificationKeyHash.getAndRequireEquals();
+    return new NFTStateStruct({
+      name,
+      metadata,
+      storage,
+      packedData,
+      metadataVerificationKeyHash,
+    });
+  }
+
+  /**
+   * Updates the NFT's state with provided proofs and permissions.
+   *
+   * @param input - The current state of the NFT (`NFTState`).
+   * @param output - The desired new state of the NFT (`NFTState`).
+   * @param creator - The public key of the creator (`PublicKey`).
+   * @returns The hash of the metadata verification key (`Field`).
+   */
+  @method.returns(Field)
+  async update(
+    input: NFTState,
+    output: NFTState,
+    creator: PublicKey
+  ): Promise<Field> {
+    const name = this.name.getAndRequireEquals();
+    const metadata = this.metadata.getAndRequireEquals();
+    const data = NFTData.unpack(this.packedData.getAndRequireEquals());
+    const owner = data.owner;
+
+    const storage = this.storage.getAndRequireEquals();
+    const metadataVerificationKeyHash =
+      this.metadataVerificationKeyHash.getAndRequireEquals();
+    // Check that the metadata verification key exists
+    metadataVerificationKeyHash.assertNotEquals(
+      Field(0),
+      NftErrors.noMetadataVerificationKey
+    );
+
+    // We do not check if the NFT is paused here
+    // It is the responsibility of metadata zkProgram to check if the NFT is paused,
+    // similar to data.isPaused.assertFalse(NftErrors.nftIsPaused);
+
+    // Assert that the public input matches the NFT state
+    NFTState.assertEqual(
+      input,
+      new NFTState({
+        immutableState: new NFTImmutableState({
+          canChangeOwnerByProof: data.canChangeOwnerByProof,
+          canTransfer: data.canTransfer,
+          canApprove: data.canApprove,
+          canChangeMetadata: data.canChangeMetadata,
+          canChangeStorage: data.canChangeStorage,
+          canChangeName: data.canChangeName,
+          canChangeMetadataVerificationKeyHash:
+            data.canChangeMetadataVerificationKeyHash,
+          canPause: data.canPause,
+          address: this.address,
+          tokenId: this.tokenId,
+          id: data.id,
+        }),
+        name,
+        metadata,
+        storage,
+        owner,
+        approved: data.approved,
+        version: data.version,
+        isPaused: data.isPaused,
+        metadataVerificationKeyHash,
+        creator,
+        context: input.context,
+        oracleAddress: input.oracleAddress,
+      })
+    );
+
+    // assert that the read-only fields are not changed
+    input.creator.assertEquals(output.creator);
+    NFTTransactionContext.assertEqual(input.context, output.context);
+    input.oracleAddress.assertEquals(output.oracleAddress);
+    // Check permissions and set new state
+    name
+      .equals(output.name)
+      .not()
+      .and(data.canChangeName.not())
+      .assertFalse(NftErrors.cannotChangeName);
+    this.name.set(output.name);
+
+    metadata
+      .equals(output.metadata)
+      .not()
+      .and(data.canChangeMetadata.not())
+      .assertFalse(NftErrors.cannotChangeMetadata);
+    this.metadata.set(output.metadata);
+
+    metadataVerificationKeyHash
+      .equals(output.metadataVerificationKeyHash)
+      .not()
+      .and(data.canChangeMetadataVerificationKeyHash.not())
+      .assertFalse(NftErrors.cannotChangeMetadataVerificationKeyHash);
+    this.metadataVerificationKeyHash.set(output.metadataVerificationKeyHash);
+
+    owner
+      .equals(output.owner)
+      .not()
+      .and(data.canChangeOwnerByProof.not())
+      .assertFalse(NftErrors.cannotChangeOwner);
+
+    Storage.equals(storage, output.storage)
+      .not()
+      .and(data.canChangeStorage.not())
+      .assertFalse(NftErrors.cannotChangeStorage);
+    this.storage.set(output.storage);
+
+    data.approved
+      .equals(output.approved)
+      .not()
+      .and(data.canChangeOwnerByProof.not())
+      .assertFalse(NftErrors.cannotChangeOwner);
+
+    data.isPaused
+      .equals(output.isPaused)
+      .not()
+      .and(data.canPause.not())
+      .assertFalse(NftErrors.cannotChangePauseState);
+
+    // recursive proofs can increase the version by more than 1
+    output.version.assertGreaterThan(data.version);
+
+    data.owner = output.owner;
+    data.approved = output.approved;
+    data.version = output.version;
+
+    this.packedData.set(data.pack());
+
+    const event = new UpdateEvent({
+      name: output.name,
+      metadata: output.metadata,
+      storage: output.storage,
+      owner: output.owner,
+      approved: output.approved,
+      version: output.version,
+      isPaused: output.isPaused,
+      metadataVerificationKeyHash: output.metadataVerificationKeyHash,
+    });
+    this.emitEvent("update", event);
+    return metadataVerificationKeyHash;
+  }
+
+  /**
+   * Transfers ownership of the NFT from one user to another.
+   *
+   * @param params - The parameters for the transfer (`TransferExtendedParams`).
+   * @returns The public key of the old owner (`PublicKey`).
+   */
+  @method.returns(TransferExtendedParams)
+  async transfer(
+    params: TransferExtendedParams
+  ): Promise<TransferExtendedParams> {
+    const data = NFTData.unpack(this.packedData.getAndRequireEquals());
+    data.canTransfer.assertTrue(NftErrors.cannotChangeOwner);
+    data.isPaused.assertFalse(NftErrors.nftIsPaused);
+    const owner = data.owner;
+    const approved = data.approved;
+    params.transferByOwner = owner.equals(params.from);
+
+    owner
+      .equals(params.from)
+      .or(
+        approved
+          .equals(params.from)
+          .and(approved.equals(PublicKey.empty()).not())
+      )
+      .assertTrue(NftErrors.cannotChangeOwner);
+    params.from = owner;
+    params.approved = approved;
+    const version = data.version.add(1);
+    data.version = version;
+    data.approved = PublicKey.empty();
+    data.owner = params.to;
+    this.packedData.set(data.pack());
+    this.emitEvent(
+      "transfer",
+      new OwnershipChangeEvent({
+        from: owner,
+        to: params.to,
+      })
+    );
+
+    return params;
+  }
+
+  /**
+   * Transfers ownership of the NFT from one user to another.
+   *
+   * @param approved - The public key of the approved address (`PublicKey`).
+   * @returns The public key of the owner (`PublicKey`).
+   */
+  @method.returns(PublicKey)
+  async approveAddress(approved: PublicKey): Promise<PublicKey> {
+    const data = NFTData.unpack(this.packedData.getAndRequireEquals());
+    data.isPaused.assertFalse(NftErrors.nftIsPaused);
+    data.approved = approved;
+    this.packedData.set(data.pack());
+    this.emitEvent("approve", approved);
+    return data.owner;
+  }
+
+  /**
+   * Upgrades the verification key used by the NFT contract.
+   *
+   * @param vk - The new verification key (`VerificationKey`).
+   * @returns An owner public key to be checked by the Collection contract and the Boolean flag indicating if the owner's authorization is required
+   */
+  @method.returns(UpgradeVerificationKeyData)
+  async upgradeVerificationKey(
+    vk: VerificationKey
+  ): Promise<UpgradeVerificationKeyData> {
+    const data = NFTData.unpack(this.packedData.getAndRequireEquals());
+
+    const version = data.version.add(1);
+    data.version = version;
+    this.account.verificationKey.set(vk);
+    this.packedData.set(data.pack());
+    return new UpgradeVerificationKeyData({
+      owner: data.owner,
+      isOwnerApprovalRequired: data.requireOwnerAuthorizationToUpgrade,
+    });
+  }
+
+  /**
+   * Pauses the NFT, disabling certain actions.
+   *
+   * @returns An owner public key to be checked by the Collection contract
+   */
+  @method.returns(PublicKey)
+  async pause(): Promise<PublicKey> {
+    const data = NFTData.unpack(this.packedData.getAndRequireEquals());
+    data.canPause.assertTrue(NftErrors.noPermissionToPause);
+    data.isPaused.assertFalse(NftErrors.nftAlreadyPaused);
+    data.isPaused = Bool(true);
+    this.packedData.set(data.pack());
+    this.emitEvent("pause", new PauseEvent({ isPaused: Bool(true) }));
+    return data.owner;
+  }
+
+  /**
+   * Resumes the NFT, re-enabling actions.
+   *
+   * @returns An owner public key to be checked by the Collection contract
+   */
+  @method.returns(PublicKey)
+  async resume(): Promise<PublicKey> {
+    const data = NFTData.unpack(this.packedData.getAndRequireEquals());
+    data.canPause.assertTrue(NftErrors.noPermissionToPause);
+    data.isPaused.assertTrue(NftErrors.nftIsNotPaused);
+    data.isPaused = Bool(false);
+    this.packedData.set(data.pack());
+    this.emitEvent("resume", new PauseEvent({ isPaused: Bool(false) }));
+    return data.owner;
+  }
+}

package/src/contracts.ts

@@ -0,0 +1,107 @@
+import { CollectionFactory, NFTAdmin } from "./contracts/index.js";
+import { NFTAdvancedAdminContract } from "./admin/index.js";
+import { VerificationKeyUpgradeAuthority } from "@silvana-one/upgradable";
+import { OfferFactory } from "./marketplace/offer.js";
+import {
+  NFTOwnerContractConstructor,
+  NFTAdminContractConstructor,
+  NFTApprovalContractConstructor,
+  NFTStandardOwner,
+  DefineApprovalFactory,
+  DefineOwnerFactory,
+  DefineUpdateFactory,
+  NFTStandardUpdate,
+  NFTUpdateContractConstructor,
+} from "./interfaces/index.js";
+
+export const NFTAdvancedAdmin = NFTAdvancedAdminContract({
+  upgradeContract: VerificationKeyUpgradeAuthority,
+});
+
+export type NonFungibleTokenContracts = {
+  Collection: ReturnType<typeof CollectionFactory>;
+  Approval: NFTApprovalContractConstructor;
+  Owner: NFTOwnerContractConstructor;
+  Admin: NFTAdminContractConstructor;
+  Update: NFTUpdateContractConstructor;
+};
+
+export function NonFungibleTokenContractsFactory(params: {
+  adminContract?: NFTAdminContractConstructor;
+  approvalFactory?: DefineApprovalFactory;
+  ownerFactory?: DefineOwnerFactory;
+  updateFactory?: DefineUpdateFactory;
+}): NonFungibleTokenContracts {
+  const {
+    adminContract = NFTAdmin,
+    approvalFactory = OfferFactory,
+    ownerFactory = ({ collectionContract }) => NFTStandardOwner,
+    updateFactory = ({ collectionContract }) => NFTStandardUpdate,
+  } = params;
+
+  let Collection: ReturnType<typeof CollectionFactory>;
+  let Approval: NFTApprovalContractConstructor;
+  let Owner: NFTOwnerContractConstructor;
+  let Admin: NFTAdminContractConstructor = adminContract;
+  let Update: NFTUpdateContractConstructor;
+
+  function getCollection() {
+    if (!Collection) {
+      throw new Error("Collection constructor not set up yet!");
+    }
+    return Collection;
+  }
+  function getApproval() {
+    if (!Approval) {
+      throw new Error("Approval constructor not set up yet!");
+    }
+    return Approval;
+  }
+
+  function getUpdate() {
+    if (!Update) {
+      throw new Error("Update constructor not set up yet!");
+    }
+    return Update;
+  }
+
+  function getOwner() {
+    if (!Owner) {
+      throw new Error("Owner constructor not set up yet!");
+    }
+    return Owner;
+  }
+
+  Approval = approvalFactory({
+    collectionContract: getCollection,
+  });
+
+  Update = updateFactory({
+    collectionContract: getCollection,
+  });
+
+  Collection = CollectionFactory({
+    adminContract: () => adminContract,
+    ownerContract: getOwner,
+    approvalContract: getApproval,
+    updateContract: getUpdate,
+  });
+
+  Owner = ownerFactory({
+    collectionContract: getCollection,
+  });
+
+  return { Collection, Approval, Owner, Admin, Update };
+}
+
+export const { Collection, Approval, Owner, Admin, Update } =
+  NonFungibleTokenContractsFactory({});
+
+export const {
+  Collection: AdvancedCollection,
+  Approval: AdvancedApproval,
+  Owner: AdvancedOwner,
+  Admin: AdvancedAdmin,
+} = NonFungibleTokenContractsFactory({
+  adminContract: NFTAdvancedAdmin,
+});

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./admin/index.js";
+export * from "./contracts/index.js";
+export * from "./metadata/index.js";
+export * from "./zkprogram-example/index.js";
+export * from "./marketplace/index.js";
+export * from "./vk.js";
+export * from "./contracts.js";
+export * from "./interfaces/index.js";

package/src/interfaces/admin.ts

@@ -0,0 +1,127 @@
+import {
+  Bool,
+  PublicKey,
+  SmartContract,
+  VerificationKey,
+  Field,
+  UInt32,
+  UInt64,
+} from "o1js";
+import { MintParamsOption, MintRequest, NFTState } from "./types.js";
+import { TransferEvent } from "./events.js";
+export { NFTAdminBase, NFTAdminContractConstructor };
+
+/**
+ * The `NFTAdminBase` interface defines the administrative functionalities required for managing an NFT collection on the Mina Protocol.
+ * It extends the `SmartContract` class and specifies methods that enforce permissions and validations for various NFT operations.
+ */
+type NFTAdminBase = SmartContract & {
+  /**
+   * Validates whether a new NFT can be minted based on the provided `MintRequest`.
+   *
+   * @param nft - The mint request containing details of the NFT to be minted.
+   * @returns A `Promise` resolving to `MintParamsOption`, containing mint parameters if minting is allowed, or an empty option if not.
+   */
+  canMint(nft: MintRequest): Promise<MintParamsOption>;
+
+  /**
+   * Checks if an NFT can be updated from its current state (`input`) to a new state (`output`).
+   *
+   * @param input - The current state of the NFT.
+   * @param output - The desired new state of the NFT.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the update is permitted.
+   */
+  canUpdate(input: NFTState, output: NFTState): Promise<Bool>;
+
+  /**
+   * Determines if an NFT can be transferred from one owner (`from`) to another (`to`) for a specific NFT contract address.
+   *
+   * @param transferEvent - The transfer event containing details of the transfer.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the transfer is allowed.
+   */
+  canTransfer(transferEvent: TransferEvent): Promise<Bool>;
+
+  /**
+   * Determines if the name can be changed for a Collection.
+   *
+   * @param name - The new name for the Collection.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the name change is allowed.
+   */
+  canChangeName(name: Field): Promise<Bool>;
+
+  /**
+   * Determines if the creator can be changed for a Collection.
+   *
+   * @param creator - The new creator for the Collection.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the creator change is allowed.
+   */
+  canChangeCreator(creator: PublicKey): Promise<Bool>;
+
+  /**
+   * Determines if the base URI can be changed for a Collection.
+   *
+   * @param baseUri - The new base URI for the Collection.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the base URI change is allowed.
+   */
+  canChangeBaseUri(baseUri: Field): Promise<Bool>;
+
+  /**
+   * Determines if the royalty fee can be changed for a Collection.
+   *
+   * @param royaltyFee - The new royalty fee for the Collection.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the royalty fee change is allowed.
+   */
+  canChangeRoyalty(royaltyFee: UInt32): Promise<Bool>;
+
+  /**
+   * Determines if the transfer fee can be changed for a Collection.
+   *
+   * @param transferFee - The new transfer fee for the Collection.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the transfer fee change is allowed.
+   */
+  canChangeTransferFee(transferFee: UInt64): Promise<Bool>;
+
+  /**
+   * Determines if the admin contract can be changed for a Collection.
+   *
+   * @param admin - The new admin for the Collection.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the admin contract change is allowed.
+   */
+  canSetAdmin(admin: PublicKey): Promise<Bool>;
+
+  /**
+   * Determines if the collection can be paused.
+   *
+   * @returns A `Promise` resolving to a `Bool` indicating whether the collection can be paused.
+   */
+  canPause(): Promise<Bool>;
+
+  /**
+   * Determines if the collection can be resumed.
+   *
+   * @returns A `Promise` resolving to a `Bool` indicating whether the collection can be resumed.
+   */
+  canResume(): Promise<Bool>;
+
+  /**
+   * Determines if the verification key can be changed for a specific NFT contract address and token ID.
+   *
+   * @param vk - The verification key to be changed.
+   * @param address - The public key of the NFT contract address or CollectionContract address.
+   * @param tokenId - The token ID of the NFT.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the verification key change is allowed.
+   */
+  canChangeVerificationKey(
+    vk: VerificationKey,
+    address: PublicKey,
+    tokenId: Field
+  ): Promise<Bool>;
+};
+
+/**
+ * Defines a constructor for contracts implementing `NFTAdminBase`, accepting an `address` public key and returning an instance of `NFTAdminBase`.
+ *
+ * @param address - The contract's address.
+ * @returns An instance of `NFTAdminBase`.
+ */
+type NFTAdminContractConstructor = new (address: PublicKey) => NFTAdminBase;

package/src/interfaces/approval.ts

@@ -0,0 +1,99 @@
+import {
+  AccountUpdate,
+  Bool,
+  method,
+  PublicKey,
+  SmartContract,
+  state,
+  State,
+  Permissions,
+  DeployArgs,
+} from "o1js";
+import { NFTCollectionContractConstructor } from "./collection.js";
+import { TransferExtendedParams } from "./types.js";
+export {
+  NFTApprovalBase,
+  NFTApprovalContractConstructor,
+  NFTStandardApproval,
+  NFTApprovalDeployProps,
+  DefineApprovalFactory,
+};
+type DefineApprovalFactory = (params: {
+  collectionContract: () => NFTCollectionContractConstructor;
+}) => NFTApprovalContractConstructor;
+
+/**
+ * The `NFTApprovalBase` interface defines the administrative functionalities required for managing an NFT transfer approval on the Mina Protocol.
+ */
+type NFTApprovalBase = SmartContract & {
+  /**
+   * Determines if an NFT can be transferred from one owner (`from`) to another (`to`) for a specific NFT contract address.
+   *
+   * @param params - The transfer details.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the transfer is allowed.
+   */
+  canTransfer(params: TransferExtendedParams): Promise<Bool>;
+};
+
+/**
+ * Defines a constructor for contracts implementing `NFTApprovalBase`, accepting an `address` public key and returning an instance of `NFTApprovalBase`.
+ *
+ * @param address - The public key of the contract's owner.
+ * @returns An instance of `NFTApprovalBase`.
+ */
+type NFTApprovalContractConstructor = new (
+  address: PublicKey
+) => NFTApprovalBase;
+
+interface NFTApprovalDeployProps extends Exclude<DeployArgs, undefined> {
+  admin: PublicKey;
+  uri: string;
+}
+
+/**
+ * The **NFTStandardApproval** contract is the default implementation of the `NFTApprovalBase` interface.
+ */
+class NFTStandardApproval extends SmartContract implements NFTApprovalBase {
+  /**
+   * The public key of the contract's administrator.
+   * This account has the authority to perform administrative actions such as pausing the contract or upgrading the verification key.
+   */
+  @state(PublicKey) admin = State<PublicKey>();
+
+  /**
+   * Deploys the contract with initial settings.
+   * @param props - Deployment properties including admin, upgradeAuthority, uri, canPause, and isPaused.
+   */
+  async deploy(props: NFTApprovalDeployProps) {
+    await super.deploy(props);
+    this.admin.set(props.admin);
+    this.account.zkappUri.set(props.uri);
+    this.account.permissions.set({
+      ...Permissions.default(),
+      setVerificationKey: Permissions.VerificationKey.signature(),
+      setPermissions: Permissions.impossible(),
+    });
+  }
+
+  /**
+   * Ensures that the transaction is authorized by the contract owner.
+   * @returns A signed `AccountUpdate` from the admin.
+   */
+  async ensureOwnerSignature(): Promise<AccountUpdate> {
+    const admin = this.admin.getAndRequireEquals();
+    const adminUpdate = AccountUpdate.createSigned(admin);
+    adminUpdate.body.useFullCommitment = Bool(true); // Prevent memo and fee change
+    return adminUpdate;
+  }
+  /**
+   * Determines if an NFT can be transferred.
+   *
+   * @param params - The transfer details.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the transfer is allowed.
+   */
+  @method.returns(Bool)
+  async canTransfer(params: TransferExtendedParams): Promise<Bool> {
+    await this.ensureOwnerSignature();
+    return Bool(true);
+  }
+}