Skip to main content

Walkthrough

Initialization​

After installing the package successfully, you can import services, initialize them and start using them. We will go through each services with examples.

note

Contract state changes requires a signer. If you are using a wallet, you can pass the wallet instance to the config object. However, for the view functions, only a valid provider is required. For providers you can visit Alchemy or INFURA. And also for Metamask connections or other wallet connections, you can use check WalletConnect. And pass the signer to the config object.

It is suggested to use ethers.js library for wallet and provider management.

Registry Service​

Mainly used for;

  • Registering and deploying entity contracts

Registry Service is the first service that you need to initialize if you are not registered yet and haven't created an entity. Using this service, it is easy to register and deploy your entity contract to the blockchain. To do that call registerEntity function with the required parameters and it will return deployed entity contract address.

Check here for more information.

import { Registry } from "mquark-sdk";

and inititialize the service with the config object;

const wallet = new ethers.Wallet("<PRIVATE KEY>", ethers.getDefaultProvider("<PROVIDER>"));

const config = {
  signerOrProvider: wallet,
  is_testnet: true,
};

const registryService = Registry.init(config);

An example usage of the service;

const registryOptions: RegistryOptions = {
  entityName: "My Entity",
  description: "My Entity Description",
  thumbnail: "ipfs://QmZ4Z",
  entitySlotDefaultURI: "ipfs://QmZ4Z",
  slotPrice: "10000000000",
};

const deployedEntity = await registryService.registerEntity(registryOptions);

Let's go through the options;

  • entityName is the name of your entity.
  • description is the description of your entity.
  • thumbnail is the thumbnail of your entity. It is an IPFS URI here, but it can be any URL.
  • entitySlotDefaultURI this one will be used when an NFT owner subscribed to your entity for the first time. This will be initial metadata for entity subscriptions.
  • slotPrice is the price of the subscription. It is in wei.

Returned value;

  • deployedEntity is the address of the deployed entity contract. We are going to use this address to initialize the Entity Service.
note

Owner of the Deployed Entity contract will be the signer of the transaction. So, make sure you are using the correct wallet.

Entity Service​

Mainly used for;

  • Creating and deploying NFT Collection contracts

Entity Service is the service after you have registered your entity and deployed it to the blockchain. Initilization of this service requires an additional entity contract address. After initialization, you can call the createCollection of the entity contract and start to create your first NFT collection.

Check here for more information.

import { Entity } from "mquark-sdk";

and inititialize the service with the config object and the deployed entity contract address;

const wallet = new ethers.Wallet("<PRIVATE KEY>", ethers.getDefaultProvider("<PROVIDER>"));

const config = {
  signerOrProvider: wallet,
  is_testnet: true,
};

const registryService = Entity.init(config, deployedEntity);

An example usage of the service;

const collectionParams: CollectionParams = {
  templateId: "1",
  collectionURIs: ["ipfs://test"],
  totalSupply: "10000",
  mintPrice: "1000000000000000000",
  mintPerAccountLimit: "1",
  name: "Best Cat Collection",
  symbol: "BSC",
  isWhitelisted: false,
};

const deployedCollection = await entityService.createCollection(collectionParams, false, "0");

You can check createCollection function here.

Let's go through the CollectionParams;

  • templateId is the template id of the collection. If you don't know what a template is please read our glossary here.If you want to query avaliable templates from the blockchain, you either call templateUri function in the Template contract, or you can use our API.
  • collectionURIs is the collection URIs. It is an array of IPFS URIs. You can use our API to upload your collection to IPFS, or simply any URL that points to metadata. Passing a single URI here refers that the collection is going to be static. If you want to make your collection limited-dynamic, you can pass multiple URIs here. So that, users can mint from any provided URIs. Also, if you want to make your fully dynamic, you should pass an empty array here, and second parameter of the createCollection function should be true. This will make your collection fully dynamic.

You can learn more about here.

caution

If you pass multiple URIs but set the second parameter to true, it will not throw an error, however, passed URIs will be ignored.

  • totalSupply is the total supply of the collection.
  • mintPrice is the price of the minting. It is in wei.It can also be zero, however, this will mark your collection as free and lock the subscription functionality for minted NFTs. But, it can be unlocked later by paying the selected template's price.
  • mintPerAccountLimit is the limit of minting per account. It can be zero, which means there is no limit.
  • name is the name of the collection.
  • symbol is the symbol of the collection.
  • verifier is an optional value, only requried if the collection is dynamic .It is the address of the verifier address which is going to be used during signature checks. It should be an externally owned account. Read dynamic collections here for more information.
  • isWhitelisted is the boolean value that determines if the collection is whitelisted or not. If it is whitelisted, only whitelisted addresses can mint from this collection. If it is not whitelisted, anyone can mint from this collection.
tip

To learn more about this feature read here. And to generate whitelist addresses, you can use our Merkle Tree generator tool here

Second Parameter of the createCollection function;

  • _isDynamicUri is the boolean value that determines if the collection is dynamic or not. If it is dynamic, users can mint from any URI that is passed to the collection. If it is not dynamic, users can only mint from pre-determined URIs that are passed to the collection.

Third Paramet of the createCollection function;

  • _ERCimplementation 0 for ERC721 NFTs, 1 for ERC1155 NFTs.
tip

If you are not sure which implementation to use, you can safely pass 0 here. Because ERC721 is the most common implementation of NFTs.

Fourth Parameter of the createCollection function;

  • _merkelRoot is the merkel root of the whitelist addresses. It is optional and is required if the collection is whitelisted.
caution

Merkle root is immutable and cannot be changed after the collection is created. So, make sure you are passing the correct merkle root.

note

So far, we have created an entity and a collection from that entity and deployed it to the blockchain. Now, we can start to mint NFTs from the collection.

Collection Service​

Mainly used for;

  • Minting NFTs

Collection Service is the service after you have created your NFT collection and deployed it to the blockchain. Initilization of this service requires an additional collection contract address. After initialization, you can call the mint function of the collection contract and start to mint your first NFT.

Check here for more information.

import { Collection } from "mquark-sdk";

and inititialize the service with the config object and the deployed collection contract address;

const wallet = new ethers.Wallet("<PRIVATE KEY>", ethers.getDefaultProvider("<PROVIDER>"));

const config = {
  signerOrProvider: wallet,
  is_testnet: true,
};

const collectionService = Collection.init(config, deployedCollection);

An example usage of the service;

const mintOptions: MintOptions = {
  value: "1",
  type: "paid",
  model: "static",
  isWhitelisted: false,
  variation: "0",
};

const { tokenId, to, entityId, templateId, collectionId, amount, uri } = await collectionService.mint(mintOptions);

You can check mint function here.

Let's go through the MintOptions;

  • value is the value that is going to be paid for the minting. It is in Ether. If the collection is free, you can pass zero here.
  • type is the type of the minting. It can be paid or free. If the collection is free, you can pass free here.
  • model is the collection model(type). It can be static , dynamic or limited. If the collection is static, you can pass static here.
  • isWhitelisted is the boolean value that determines if the collection is whitelisted or not.
  • variation is an optinal value. It refers the variation(index) of the URI. If the collection is static, you can pass 0 here.

Returned values;

  • tokenId is the id of the minted NFT.
  • to is the address of the receiver.
  • entityId is the id of the entity that the collection belongs to.
  • templateId is the id of the template that the collection belongs to.
  • collectionId is the id of the collection.
  • amount is the minted amount of the collection.
  • uri is the URI of the minted NFT.

Subscription Service​

Mainly used for;

  • Subscribing NFTs to entities, upgradibilty, unlocking free NFTs.

This service interacts wiht Subscriber contract and provides the functionality to subscribe NFTs to entities, upgrade NFTs, unlock free NFTs and more.

import { Subscription } from "mquark-sdk";

const subscription = Subscription.init(mintConfig);
await subscription.subscribeToEntity("4","0x753ef8763ebb89a479957fbd5c644db9b034cc09","1","10000000000000")

Parameters of the subscribeToEntity function;

  • `tokenId is the id of the NFT that is going to be subscribed to the entity.
  • contractAddress is the address of the collection contract that the NFT belongs to.
  • entityId is the id of the entity that the NFT is going to be subscribed to.
  • subscriptionPrice is the price of the subscription. It is in wei.
tip

To be able to see the subscription asset, you can call the tokenEntityURI function of the collection contract. It will return the URI of the subscription asset.Also it is possible to query the subscription asset from our API service. You can check here for more information.