Skip to main content

Skeleton and Rust Architecture

In this article, you'll learn about the basic architecture behind the NFT contract that you'll develop while following this "Zero to Hero" series.

You'll discover the contract's layout and you'll see how the Rust files are structured in order to build a feature-complete smart contract.

Skeleton Contract

You can find the skeleton contract in our GitHub repository

New to Rust?

If you are new to Rust and want to dive into smart contract development, our Quick-start guide is a great place to start.


Introductionโ€‹

This tutorial presents the code skeleton for the NFT smart contract and its file structure.

Once every file and functions have been covered, we will guide you through the process of building the mock-up contract to confirm that your Rust setup works.


File structureโ€‹

Following a regular Rust project, the file structure for this smart contract has:

nft-contract
โ”œโ”€โ”€ Cargo.lock
โ”œโ”€โ”€ Cargo.toml
โ”œโ”€โ”€ README.md
โ””โ”€โ”€ src
โ”œโ”€โ”€ approval.rs
โ”œโ”€โ”€ enumeration.rs
โ”œโ”€โ”€ lib.rs
โ”œโ”€โ”€ metadata.rs
โ”œโ”€โ”€ mint.rs
โ”œโ”€โ”€ nft_core.rs
โ”œโ”€โ”€ events.rs
โ””โ”€โ”€ royalty.rs
  • The file Cargo.toml defines the code dependencies
  • The src folder contains all the Rust source files

Source filesโ€‹

Here is a brief description of what each source file is responsible for:

FileDescription
approval.rsHas the functions that controls the access and transfers of non-fungible tokens
enumeration.rsContains the methods to list NFT tokens and their owners
lib.rsHolds the smart contract initialization functions
metadata.rsDefines the token and metadata structure
mint.rsContains token minting logic
nft_core.rsCore logic that allows you to transfer NFTs between users.
royalty.rsContains payout-related functions
events.rsContains events related structures
tip

Explore the code in our GitHub repository.


approval.rsโ€‹

This allows people to approve other accounts to transfer NFTs on their behalf.

This file contains the logic that complies with the standard's approvals management extension. Here is a breakdown of the methods and their functions:

MethodDescription
nft_approveApproves an account ID to transfer a token on your behalf.
nft_is_approvedChecks if the input account has access to approve the token ID.
nft_revokeRevokes a specific account from transferring the token on your behalf.
nft_revoke_allRevokes all accounts from transferring the token on your behalf.
nft_on_approveThis callback function, initiated during nft_approve, is a cross contract call to an external contract.

You'll learn more about these functions in the approvals section of the Zero to Hero series.


enumeration.rsโ€‹

This file provides the functions needed to view information about NFTs, and follows the standard's enumeration extension.

MethodDescription
nft_total_supplyReturns the total amount of NFTs stored on the contract
nft_tokensReturns a paginated list of NFTs stored on the contract regardless of their owner.
nft_supply_for_ownerAllows you view the total number of NFTs owned by any given user
nft_tokens_for_ownerReturns a paginated list of NFTs owned by any given user

You'll learn more about these functions in the enumeration section of the tutorial series.


lib.rsโ€‹

This file outlines what information the contract stores and keeps track of.

MethodDescription
new_default_metaInitializes the contract with default metadata so the user doesn't have to provide any input.
newInitializes the contract with the user-provided metadata.
Keep in mind

The initialization functions (new, new_default_meta) can only be called once.

You'll learn more about these functions in the minting section of the tutorial series.


metadata.rsโ€‹

This file is used to keep track of the information to be stored for tokens, and metadata. In addition, you can define a function to view the contract's metadata which is part of the standard's metadata extension.

NameDescription
TokenMetadataThis structure defines the metadata that can be stored for each token (title, description, media, etc.).
TokenThis structure outlines what information will be stored on the contract for each token.
JsonTokenWhen querying information about NFTs through view calls, the return information is stored in this JSON token.
nft_metadataThis function allows users to query for the contact's internal metadata.

You'll learn more about these functions in the minting section of the tutorial series.


mint.rsโ€‹

Contains the logic to mint the non-fungible tokens

MethodDescription
nft_mintThis function mints a non-fungible token.

nft_core.rsโ€‹

Core logic that allows to transfer NFTs between users.

MethodDescription
nft_transferTransfers an NFT to a receiver ID.
nft_transfer_callTransfers an NFT to a receiver and calls a function on the receiver ID's contract. The function returns true if the token was transferred from the sender's account.
nft_tokenAllows users to query for the information about a specific NFT.
nft_on_transferCalled by other contracts when an NFT is transferred to your contract account via the nft_transfer_call method. It returns true if the token should be returned back to the sender.
nft_resolve_transferWhen you start the nft_transfer_call and transfer an NFT, the standard also calls a method on the receiver's contract. If the receiver needs you to return the NFT to the sender (as per the return value of the nft_on_transfer method), this function allows you to execute that logic.

You'll learn more about these functions in the core section of the tutorial series.


royalty.rsโ€‹

Contains payout-related functions.

MethodDescription
nft_payoutThis view method calculates the payout for a given token.
nft_transfer_payoutTransfers the token to the receiver ID and returns the payout object that should be paid for a given balance.

You'll learn more about these functions in the royalty section of the tutorial series.


events.rsโ€‹

Contains events-related structures.

MethodDescription
EventLogVariantThis enum represents the data type of the EventLog.
EventLogInterface to capture data about an event.
NftMintLogAn event log to capture token minting.
NftTransferLogAn event log to capture token transfer.

You'll learn more about these functions in the events section of the tutorial series.


Building the skeletonโ€‹

If you haven't cloned the main repository yet, open a terminal and run:

git clone https://github.com/near-examples/nft-tutorial/

Next, go to the nft-contract-skeleton/ folder and build the contract with cargo-near:

cd nft-tutorial
cd nft-contract-skeleton/
cargo near build

Since this source is just a skeleton you'll get many warnings about unused code, such as:

   Compiling nft_contract_skeleton v0.1.0 (/Users/near-examples/Documents/my/projects/near/examples/nft-tutorial/nft-contract-basic)
โ”‚ warning: unused imports: `LazyOption`, `LookupMap`, `UnorderedMap`, `UnorderedSet`
โ”‚ --> src/lib.rs:3:29
โ”‚ |
โ”‚ 3 | use near_sdk::collections::{LazyOption, LookupMap, UnorderedMap, UnorderedSet};
โ”‚ | ^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^^^^^
โ”‚ |
โ”‚ = note: `#[warn(unused_imports)]` on by default
โ”‚
โ”‚ warning: unused import: `Base64VecU8`
โ”‚ --> src/lib.rs:4:28
โ”‚ |
โ”‚ 4 | use near_sdk::json_types::{Base64VecU8, U128};
โ”‚ |

โ”‚ warning: `nft_contract_skeleton` (lib) generated 48 warnings (run `cargo fix --lib -p nft_contract_skeleton` to apply 45 suggestions)
โ”‚ Finished release [optimized] target(s) in 11.01s
โœ“ Contract successfully built!

Don't worry about these warnings, you're not going to deploy this contract yet. Building the skeleton is useful to validate that your Rust toolchain works properly and that you'll be able to compile improved versions of this NFT contract in the upcoming tutorials.


Conclusionโ€‹

You've seen the layout of this NFT smart contract, and how all the functions are laid out across the different source files. Using yarn, you've been able to compile the contract, and you'll start fleshing out this skeleton in the next Minting tutorial.

Versioning for this article

At the time of this writing, this example works with the following versions:

  • rustc: 1.76.0
  • near-sdk-rs: 5.1.0
  • cargo-near: 0.6.1
  • NFT standard: NEP171, version 1.0.0
Was this page helpful?