Skip to main content

Vara Non-Fungible Token

note

The Vara Non-Fungible Token Standard is the analogue of ERC-721 on Ethereum.

The Vara Non-Fungible Token Standard outlines a unified API for implementing non-fungible token functionalities in programs. The initial section of this document provides a comprehensive examination of the core VNFT service, which serves as a foundational framework. It covers essential operations such as token transfers and approvals for third-party spending, detailing the contract state, interface, and key methods involved. The source code of the standard-service is avaiable on the GitHub.

The subsequent section expands on how to leverage and extend this core service to develop a fully functional token application. It illustrates the process of adding advanced features like minting and burning, demonstrating how to build upon the core VNFT service to create a comprehensive and customizable token system. This extension highlights the flexibility and potential of the core standard, providing a pathway to develop more sophisticated and tailored token solutions. The source code of the extended version is avaiable on the GitHub.

tip

The project code is developed using the Sails framework.

Functions​

  Approve(to, token_id)
  Transfer(to, token_id)
  TransferFrom(from, to, token_id)
  OwnerOf(token_id)
  BalanceOf(owner) 
  GetApproved(token_id)
  Name()
  Symbol()

Events​

    Approval(owner, approved, token_id);
    Transfer(from, to, token_id);

Key Methods​

Approve​

pub fn approve(&mut self, approved: ActorId, token_id: TokenId)

This function authorizes a designated account (approved) to transfer the specified NFT (token_id) on behalf of the owner. Only one account can be approved at a time for a specific NFT. If the function is called again with a different approved address, it overrides the previous approval. If the function is called with the zero address as approved, it cancels the existing approval. This action triggers the Approval event:

Approval {
    owner: ActorId,
    approved: ActorId,
    token_id: TokenId,
}

Transfer​

pub fn transfer(&mut self, to: ActorId, token_id: TokenId)

This function transfers ownership of a specific NFT (token_id) to another account (to). The caller must be the current owner of the NFT. Upon successful execution, it generates the Transfer event:

Transfer {
    from: ActorId,
    to: ActorId,
    token_id: TokenId,
}

TransferFrom​

pub fn transfer_from(&mut self, from: ActorId, to: ActorId, token_id: TokenId)

This function facilitates the transfer of an NFT from one account (from) to another (to), using the approval mechanism. It allows a third party to transfer an NFT on behalf of its owner, provided the caller has been previously approved. The function triggers the Transfer event upon success:

Transfer {
    from: ActorId,
    to: ActorId,
    token_id: TokenId,
}

Query Methods​

owner_of​

Returns the owner of a specified NFT (token_id).

pub fn owner_of(&self, token_id: TokenId) -> ActorId

balance_of​

Returns the number of NFTs owned by a specific account (owner).

pub fn balance_of(&self, owner: ActorId) -> U256

get_approved​

Returns the account approved to transfer a specific NFT (token_id), or the zero address if no approval exists.

pub fn get_approved(&self, token_id: TokenId) -> ActorId

name​

Returns the name of the NFT collection.

pub fn name(&self) -> String

symbol​

Returns the symbol of the NFT collection.

pub fn symbol(&self) -> String
note

The service provided here is not a complete application but serves as a foundational base or core for creating your own token. It can be extended and inherited to add additional functionality, allowing developers to build upon this framework. The code for this service is available on GitHub. The extended version demonstrates how to utilize this base service to create a fully functional application, showcasing the process of expanding its capabilities into a finished program.

Extended VNFT Implementation​

Additional Features​

The extended implementation introduces new functions and events that enhance the basic VNFT service. The additional features include:

Functions​

  • Mint(to, token_metadata)
  • Burn(from, token_id)
  • GrantAdminRole(to)
  • GrantBurnerRole(to)
  • GrantMinterRole(to)
  • RevokeAdminRole(from)
  • RevokeBurnerRole(from)
  • RevokeMinterRole(from)
  • Admins()
  • Burners()
  • Minters()

Events​

  • Minted(to, token_metadata)
  • Burned(from, token_id)

Implementation Details​

To incorporate the extended functionality, the VNFT service is first added as a dependency in the Cargo.toml file:

vnft-service = { git = "https://github.com/gear-foundation/standards" }

A new service is created that extends the existing VNFT service:

use vnft_service::Service as VnftService;

pub struct ExtendedService {
    vnft: VnftService,
}

The #[service(extends = VnftService, events = Event)] attribute is used to ensure that the ExtendedService inherits methods and properties from VnftService, making all core functionalities available within the extended service.

Key Methods​

Mint​

pub fn mint(&mut self, to: ActorId, token_metadata: TokenMetadata)

This function mints new tokens and assigns them to a specified actor. The function checks if the caller has the minter role and triggers a Minted event if the minting is successful.

Burn​

pub fn burn(&mut self, from: ActorId, token_id: TokenId)

This function burns tokens from a specified actor. It checks if the caller has the burner role and triggers a Burned event if the burning is successful.

Role Management​

  • grant_admin_role(&mut self, to: ActorId)
  • grant_minter_role(&mut self, to: ActorId)
  • grant_burner_role(&mut self, to: ActorId)
  • revoke_admin_role(&mut self, from: ActorId)
  • revoke_minter_role(&mut self, from: ActorId)
  • revoke_burner_role(&mut self, from: ActorId)

These methods manage the assignment and revocation of administrative, minting, and burning roles, ensuring that only authorized actors can perform sensitive operations.

Query methods​

minters​

Returns a list of all actors who have the minter role.

pub fn minters(&self) -> Vec<ActorId>

burners​

Returns a list of all actors who have the burner role.

pub fn burners(&self) -> Vec<ActorId>

admins​

Returns a list of all actors who have the admin role.

pub fn admins(&self) -> Vec<ActorId>

tokens for owner​

Returns a list of all tokens with metadata that the owner holds.

pub fn tokens_for_owner(&self, owner: ActorId) -> Vec<(TokenId, TokenMetadata)>

Contract Interface​

The extended service incorporates the following interface:

type TokenMetadata = struct {
  name: str,
  description: str,
  media: str,
  reference: str,
};

constructor {
  New : (name: str, symbol: str);
};

service Vnft {
  Burn : (from: actor_id, token_id: u256) -> null;
  GrantAdminRole : (to: actor_id) -> null;
  GrantBurnerRole : (to: actor_id) -> null;
  GrantMinterRole : (to: actor_id) -> null;
  Mint : (to: actor_id, token_metadata: TokenMetadata) -> null;
  RevokeAdminRole : (from: actor_id) -> null;
  RevokeBurnerRole : (from: actor_id) -> null;
  RevokeMinterRole : (from: actor_id) -> null;
  Approve : (approved: actor_id, token_id: u256) -> null;
  Transfer : (to: actor_id, token_id: u256) -> null;
  TransferFrom : (from: actor_id, to: actor_id, token_id: u256) -> null;
  query Admins : () -> vec actor_id;
  query Burners : () -> vec actor_id;
  query Minters : () -> vec actor_id;
  query TokenId : () -> u256;
  query TokenMetadataById : (token_id: u256) -> opt TokenMetadata;
  query TokensForOwner : (owner: actor_id) -> vec struct { u256, TokenMetadata };
  query BalanceOf : (owner: actor_id) -> u256;
  query GetApproved : (token_id: u256) -> actor_id;
  query Name : () -> str;
  query OwnerOf : (token_id: u256) -> actor_id;
  query Symbol : () -> str;

  events {
    Minted: struct { to: actor_id, token_metadata: TokenMetadata };
    Burned: struct { from: actor_id, token_id: u256 };
    Transfer: struct { from: actor_id, to: actor_id, token_id: u256 };
    Approval: struct { owner: actor_id, approved: actor_id, token_id: u256 };
  }
};
note

The Extended VNFT implementation illustrates how the core VNFT service can be expanded to incorporate advanced features like minting, burning, and role management. This extension provides a versatile framework that developers can adapt to meet specific use cases, enabling more robust and feature-rich token systems. By leveraging these additional capabilities, the Extended VNFT offers a comprehensive foundation for creating custom token solutions within the Vara ecosystem.

For a more detailed implementation, the code for the Extended VNFT can be found on GitHub.

Conclusion​

The core VNFT service establishes a robust foundation for implementing non-fungible tokens within the Vara ecosystem, encompassing essential functionalities that adhere to recognized token standards. This service functions as a fundamental core, with the Extended VNFT illustrating how it can be expanded to incorporate advanced capabilities, including minting, burning, and role management. Together, these implementations provide a comprehensive framework for developers, facilitating the creation of tailored and sophisticated token systems. By utilizing both the core service and its extended functionalities, developers are well-positioned to design flexible and secure token solutions that address specific requirements and enhance overall system capabilities.