@silvana-one/nft 0.1.0

package/src/interfaces/collection.ts

@@ -0,0 +1,68 @@
+import { PublicKey, TokenContract } from "o1js";
+import { TransferParams, NFTStateStruct } from "./types.js";
+import { NFTOwnerContractConstructor } from "./owner.js";
+import { NFTApprovalContractConstructor } from "./approval.js";
+import { NFTUpdateContractConstructor } from "./update.js";
+import { NFTAdminContractConstructor } from "./admin.js";
+export {
+  NFTCollectionBase,
+  NFTCollectionContractConstructor,
+  DefineCollectionFactory,
+};
+
+/**
+ * The `NFTCollectionBase` interface defines the 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 NFTCollectionBase = TokenContract & {
+  /**
+   * Transfers ownership of an NFT from contract without admin approval using a proof.
+   *
+   * @param params - The transfer details.
+   */
+  transferByProof(params: TransferParams): Promise<void>;
+  /**
+   * Transfers ownership of an NFT from contract without admin approval.
+   *
+   * @param params - The transfer details.
+   */
+  transferBySignature(params: TransferParams): Promise<void>;
+
+  /**
+   * Transfers ownership of an NFT from contract without admin approval using a proof.
+   *
+   * @param params - The transfer details.
+   */
+  approvedTransferByProof(params: TransferParams): Promise<void>;
+  /**
+   * Transfers ownership of an NFT from contract without admin approval.
+   *
+   * @param params - The transfer details.
+   */
+  approvedTransferBySignature(params: TransferParams): Promise<void>;
+
+  /**
+   * Returns the state of an NFT.
+   *
+   * @param address - The address of the NFT.
+   * @returns The state of the NFT.
+   */
+  getNFTState(address: PublicKey): Promise<NFTStateStruct>;
+};
+
+/**
+ * Defines a constructor for contracts implementing `NFTCollectionBase`, accepting an `address` public key and returning an instance of `NFTCollectionBase`.
+ *
+ * @param address - The contract's address.
+ * @returns An instance of `NFTCollectionBase`.
+ */
+type NFTCollectionContractConstructor = new (
+  address: PublicKey
+) => NFTCollectionBase;
+
+type DefineCollectionFactory = (params: {
+  adminContract: () => NFTAdminContractConstructor;
+  ownerContract: () => NFTOwnerContractConstructor;
+  approvalContract: () => NFTApprovalContractConstructor;
+  updateContract: () => NFTUpdateContractConstructor;
+}) => NFTCollectionContractConstructor;

package/src/interfaces/encoding.ts

@@ -0,0 +1,32 @@
+/**
+ * Utilities for encoding and decoding `Field` elements to and from strings.
+ * These functions are used throughout the NFT standard for handling off-chain storage references and metadata.
+ */
+import { Encoding, Field } from "o1js";
+export { fieldToString, fieldFromString };
+
+/**
+ * Converts a `Field` element to a string representation.
+ * This is used for serializing `Field` values into strings suitable for storage or transmission.
+ *
+ * @param {Field} field - The `Field` element to convert.
+ * @returns {string} The string representation of the `Field`.
+ */
+function fieldToString(field: Field): string {
+  return Encoding.stringFromFields([field]);
+}
+
+/**
+ * Reconstructs a `Field` element from its string representation.
+ * This function is essential for deserializing strings back into `Field` elements,
+ * which can then be used within the smart contract logic.
+ *
+ * @param {string} storage - The string representation of the `Field`.
+ * @returns {Field} The reconstructed `Field` element.
+ * @throws Will throw an error if the input string does not correspond to exactly one `Field`.
+ */
+function fieldFromString(storage: string): Field {
+  const fields = Encoding.stringToFields(storage);
+  if (fields.length !== 1) throw new Error("String is too long");
+  return fields[0];
+}

package/src/interfaces/events.ts

@@ -0,0 +1,115 @@
+import { PublicKey, Struct, UInt32, Field, Bool } from "o1js";
+import { Storage } from "@silvana-one/storage";
+import { NFTStateStruct, UInt64Option } from "./types.js";
+
+export {
+  MintEvent,
+  UpdateEvent,
+  TransferEvent,
+  UpgradeVerificationKeyEvent,
+  UpgradeVerificationKeyData,
+  LimitMintingEvent,
+  PauseNFTEvent,
+  ApproveEvent,
+};
+
+/**
+ * Emitted when a new NFT is minted in the collection.
+ */
+class MintEvent extends Struct({
+  /** The initial state of the NFT at the time of minting. */
+  initialState: NFTStateStruct,
+  /** The public key address of the minted NFT. */
+  address: PublicKey,
+}) {}
+
+/**
+ * Emitted when an NFT's state is updated.
+ */
+class UpdateEvent extends Struct({
+  /** The updated name of the NFT. */
+  name: Field,
+  /** The updated metadata hash of the NFT. */
+  metadata: Field,
+  /** Off-chain storage information, e.g., IPFS hash. */
+  storage: Storage,
+  /** The owner of the NFT after the update. */
+  owner: PublicKey,
+  /** The approved address of the NFT after the update. */
+  approved: PublicKey,
+  /** The version number of the NFT state. */
+  version: UInt32,
+  /** Indicates whether the NFT is paused after the update. */
+  isPaused: Bool,
+  /** The hash of the verification key used for metadata proofs. */
+  metadataVerificationKeyHash: Field,
+}) {}
+
+/**
+ * Emitted when an NFT's approved address is updated.
+ */
+class ApproveEvent extends Struct({
+  /** The public key address of the NFT. */
+  nftAddress: PublicKey,
+  /** The public key of the approved address. */
+  approved: PublicKey,
+}) {}
+
+/**
+ * Emitted when an NFT is transferred from one owner to another.
+ */
+class TransferEvent extends Struct({
+  /** The public key of the sender (current owner) before the transfer. */
+  from: PublicKey,
+  /** The public key of the recipient (new owner) after the transfer. */
+  to: PublicKey,
+  /** The public key of the collection. */
+  collection: PublicKey,
+  /** The public key address of the NFT being transferred. */
+  nft: PublicKey,
+  /** The fee paid for the transfer. */
+  fee: UInt64Option,
+  /** The price of the NFT being transferred. */
+  price: UInt64Option,
+  /** Indicates whether the transfer is by owner or by approved address. */
+  transferByOwner: Bool,
+  /** The public key of the approved address. */
+  approved: PublicKey,
+}) {}
+
+/**
+ * Emitted when an NFT is paused or resumed.
+ */
+class PauseNFTEvent extends Struct({
+  /** The public key address of the NFT. */
+  address: PublicKey,
+  /** Indicates whether the NFT is paused (`true`) or resumed (`false`). */
+  isPaused: Bool,
+}) {}
+
+/**
+ * Emitted when the verification key of an NFT is upgraded.
+ */
+class UpgradeVerificationKeyEvent extends Struct({
+  /** The hash of the new verification key. */
+  verificationKeyHash: Field,
+  /** The public key address of the NFT whose verification key is upgraded. */
+  address: PublicKey,
+  /** The version number of the NFT state after the upgrade. */
+  tokenId: Field,
+}) {}
+
+class UpgradeVerificationKeyData extends Struct({
+  /** The owner of the NFT. */
+  owner: PublicKey,
+  /** Indicates whether the owner approval is required to upgrade the verification key. */
+  isOwnerApprovalRequired: Bool,
+}) {}
+
+/**
+ * Emitted when minting of new NFTs is limited in the collection.
+ */
+class LimitMintingEvent extends Struct({
+  /** Indicates whether minting is limited (`true`) or not (`false`). */
+  mintingLimited: Bool,
+}) {}

package/src/interfaces/index.ts

@@ -0,0 +1,10 @@
+export * from "./types.js";
+export * from "./encoding.js";
+export * from "./events.js";
+export * from "./admin.js";
+export * from "./pausable.js";
+export * from "./ownable.js";
+export * from "./owner.js";
+export * from "./approval.js";
+export * from "./update.js";
+export * from "./collection.js";

package/src/interfaces/ownable.ts

@@ -0,0 +1,32 @@
+import { PublicKey, SmartContract, Field, Struct, Bool } from "o1js";
+
+/**
+ * Interface representing ownable functionality for smart contracts.
+ *
+ * The `OwnableContract` interface extends `SmartContract` and provides methods to ensure that only the owner
+ * can perform certain actions and to allow the transfer of ownership to a new owner.
+ *
+ * By implementing the Ownable interface, contracts can secure critical operations and provide a transparent
+ * mechanism for ownership management.
+ *
+ * @interface
+ */
+export type OwnableContract = SmartContract & {
+  /**
+   * Transfers ownership of the contract to a new owner.
+   *
+   * @param {PublicKey} to - The public key of the new owner.
+   * @returns {Promise<PublicKey>} A promise that resolves to the public key of the old owner.
+   */
+  transferOwnership(to: PublicKey): Promise<PublicKey>; // returns the old owner
+};
+
+/**
+ * Event emitted when the ownership of the contract changes.
+ *
+ * Contains the old owner's and new owner's public keys.
+ */
+export class OwnershipChangeEvent extends Struct({
+  from: PublicKey,
+  to: PublicKey,
+}) {}

package/src/interfaces/owner.ts

@@ -0,0 +1,143 @@
+import {
+  AccountUpdate,
+  Bool,
+  DeployArgs,
+  method,
+  PublicKey,
+  SmartContract,
+  state,
+  State,
+  Permissions,
+  VerificationKey,
+} from "o1js";
+import { NFTCollectionContractConstructor } from "./collection.js";
+import { TransferExtendedParams } from "./types.js";
+export {
+  NFTOwnerBase,
+  NFTOwnerContractConstructor,
+  NFTOwnerDeployProps,
+  NFTStandardOwner,
+  DefineOwnerFactory,
+};
+type DefineOwnerFactory = (params: {
+  collectionContract: () => NFTCollectionContractConstructor;
+}) => NFTOwnerContractConstructor;
+
+/**
+ * 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 NFTOwnerBase = 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 event details.
+   * @returns A `Promise` resolving to a `Bool` indicating whether the transfer is allowed.
+   */
+  canTransfer(params: TransferExtendedParams): Promise<Bool>;
+
+  canApproveAddress(
+    collection: PublicKey,
+    nft: PublicKey,
+    approved: PublicKey
+  ): Promise<Bool>;
+
+  canPause(collection: PublicKey, nft: PublicKey): Promise<Bool>;
+
+  canResume(collection: PublicKey, nft: PublicKey): Promise<Bool>;
+
+  canChangeVerificationKey(
+    collection: PublicKey,
+    nft: PublicKey,
+    vk: VerificationKey
+  ): Promise<Bool>;
+};
+
+/**
+ * Defines a constructor for contracts implementing `NFTOwnerBase`, accepting an `address` public key and returning an instance of `NFTOwnerBase`.
+ *
+ * @param address - The public key of the contract's owner.
+ * @returns An instance of `NFTOwnerBase`.
+ */
+type NFTOwnerContractConstructor = new (address: PublicKey) => NFTOwnerBase;
+
+interface NFTOwnerDeployProps extends Exclude<DeployArgs, undefined> {
+  admin: PublicKey;
+  uri: string;
+}
+
+/**
+ * The **NFTStandardOwner** contract is the default implementation of the `NFTOwnerBase` interface.
+
+ */
+class NFTStandardOwner extends SmartContract implements NFTOwnerBase {
+  /**
+   * 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: NFTOwnerDeployProps) {
+    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;
+  }
+
+  @method.returns(Bool)
+  async canTransfer(params: TransferExtendedParams): Promise<Bool> {
+    await this.ensureOwnerSignature();
+    return Bool(true);
+  }
+
+  @method.returns(Bool)
+  async canPause(collection: PublicKey, nft: PublicKey): Promise<Bool> {
+    await this.ensureOwnerSignature();
+    return Bool(true);
+  }
+
+  @method.returns(Bool)
+  async canResume(collection: PublicKey, nft: PublicKey): Promise<Bool> {
+    await this.ensureOwnerSignature();
+    return Bool(true);
+  }
+
+  @method.returns(Bool)
+  async canChangeVerificationKey(
+    collection: PublicKey,
+    nft: PublicKey,
+    vk: VerificationKey
+  ): Promise<Bool> {
+    await this.ensureOwnerSignature();
+    return Bool(true);
+  }
+
+  @method.returns(Bool)
+  async canApproveAddress(
+    collection: PublicKey,
+    nft: PublicKey,
+    approved: PublicKey
+  ): Promise<Bool> {
+    await this.ensureOwnerSignature();
+    return Bool(true);
+  }
+}

package/src/interfaces/pausable.ts

@@ -0,0 +1,41 @@
+import { SmartContract, Field, Struct, Bool } from "o1js";
+export { PausableContract, PauseEvent };
+
+/**
+ * The **PausableContract** interface provides a mechanism to dynamically enable or disable
+ * certain functionalities within smart contracts. It extends the `SmartContract` class
+ * and introduces methods that allow a contract to be paused and resumed, which is crucial
+ * for managing emergencies, upgrades, or maintenance periods.
+ *
+ * By implementing the PausableContract interface, contracts gain greater control over their
+ * operational states, enhancing security and flexibility in response to various scenarios.
+ */
+type PausableContract = SmartContract & {
+  /**
+   * Pauses the contract, potentially halting critical operations to protect against
+   * unforeseen issues or to perform maintenance. When called, the contract enters a paused
+   * state where certain functions are restricted.
+   *
+   * @returns A promise that resolves when the contract has been successfully paused.
+   */
+  pause(): Promise<void>;
+
+  /**
+   * Resumes the contract's operations after it has been paused. This method restores
+   * the contract to its normal working state, allowing all functionalities to be accessible again.
+   *
+   * @returns A promise that resolves when the contract has been successfully resumed.
+   */
+  resume(): Promise<void>;
+};
+
+/**
+ * The **PauseEvent** class represents an event emitted whenever the contract is paused or resumed.
+ * This event contains the `isPaused` boolean field, indicating the current state of the contract.
+ */
+class PauseEvent extends Struct({
+  /**
+   * Indicates whether the contract is currently paused.
+   */
+  isPaused: Bool,
+}) {}