feat(nonfungibles): add pallet-api/nonfungibles

[chungquantin]

Description

The non-fungibles pallet offers a streamlined interface for interacting with non-fungible assets. The goal is to provide a simplified, consistent API that adheres to standards in the smart contract space. Built on top of the optimized version of the pallet-nfts (See #387).

CHANGELOG

Dispatchable Functions

transfer()

Transfers the collection item from the origin to account to.

fn transfer(origin: OriginFor<T>, collection: CollectionIdOf<T>, item: ItemIdOf<T>, to: AccountIdOf<T>) -> DispatchResult

One extra storage read for the collection item owner to emit it in the Transfer event.

approve()

Either approve or cancel approval for an operator to perform transfers of a specific collection item or all collection items owned by the origin.

• approved - A boolean indicating the desired approval status:
  • true to approve the operator.
  • false to cancel the approval granted to the operator.

fn approve(origin: OriginFor<T>, collection: CollectionIdOf<T>, item: Option<ItemIdOf<T>>, operator: AccountIdOf<T>, approved: bool) -> DispatchResultWithPostInfo 

clear_all_transfer_approvals()

Cancel all the approvals of a specific item.

fn clear_all_transfer_approvals(origin: OriginFor<T>, collection: CollectionIdOf<T>, item: ItemIdOf<T>) -> DispatchResult

clear_collection_approvals()

Cancel approvals to transfer all owner's collection items.

fn clear_collection_approvals(origin: OriginFor<T>, collection: CollectionIdOf<T>, limit: u32) -> DispatchResult

create()

Issue a new collection of non-fungible items from a public origin.

fn create(origin: OriginFor<T>, admin: AccountIdOf<T>, config: CollectionConfigFor<T>) -> DispatchResult

destroy()

Destroy a collection of fungible items.

fn destroy(origin: OriginFor<T>, collection: CollectionIdOf<T>, witness: DestroyWitness)

set_attribute()

Set an attribute for a collection or item.

fn set_attribute(origin: OriginFor<T>, collection: CollectionIdOf<T>, item: Option<ItemIdOf<T>>, namespace: AttributeNamespaceOf<T>, key: BoundedVec<u8, T::KeyLimit>, value: BoundedVec<u8, T::ValueLimit>) -> DispatchResult

clear_attribute()

Clear an attribute for the collection or item.

fn clear_attribute(origin: OriginFor<T>, collection: CollectionIdOf<T>, item: Option<ItemIdOf<T>>, namespace: AttributeNamespaceOf<T>, key: BoundedVec<u8, T::KeyLimit>)  -> DispatchResult

set_metadata()

Set the metadata for an item.

fn set_metadata(origin: OriginFor<T>, collection: CollectionIdOf<T>, item: ItemIdOf<T>, data: BoundedVec<u8, T::StringLimit>) -> DispatchResult

approve_item_attribute()

fn approve_item_attributes(origin: OriginFor<T>, collection: CollectionIdOf<T>, item: ItemIdOf<T>, delegate: AccountIdOf<T>)

cancel_item_attributes_approval()

Cancel the previously provided approval to change item's attributes. All the previously set attributes by the delegate will be removed.

fn cancel_item_attributes_approval(origin: OriginFor<T>,collection: CollectionIdOf<T>,item: ItemIdOf<T>,delegate: AccountIdOf<T>,witness: CancelAttributesApprovalWitness,) -> DispatchResult 

set_max_supply()

Set the maximum number of items a collection could have.

fn set_max_supply(origin: OriginFor<T>, collection: CollectionIdOf<T>, max_supply: u32) -> DispatchResult 

mint()

Mint an item of a particular collection.

fn mint(origin: OriginFor<T>, to: AccountIdOf<T>, collection: CollectionIdOf<T>, item: ItemIdOf<T>, witness: MintWitness<ItemIdOf<T>, ItemPriceOf<T>>) -> DispatchResult

burn()

Destroy a single collection item.

fn burn(origin: OriginFor<T>, collection: CollectionIdOf<T>, item: ItemIdOf<T>) -> DispatchResult

Events

• Approval: Event emitted when allowance by owner to operator changes.
• Transfer: Event emitted when a token transfer occurs.
• Created: Event emitted when a collection is created.

Reads

• TotalSupply: Total item supply of a specified collection.
• BalanceOf: Account balance for a specified collection.
• Allowance: Allowance for an operator approved by an owner, for a specified collection or item.
• OwnerOf: Owner of a specified collection item.
• GetAttribute: Attribute value of a specified collection item.
• Collection: Details of a specified collection.
• NextCollectionId: Next collection ID.
• ItemMetadata: Metadata of a specified collection item.

Read Result

Results of state reads for the non-fungibles API.

pub enum ReadResult<T: Config> {
	/// Total item supply of a collection.
	TotalSupply(u128),
	/// Account balance for a specified collection.
	BalanceOf(u32),
	/// Allowance for an operator approved by an owner, for a specified collection or item.
	Allowance(bool),
	/// Owner of a specified collection owner.
	OwnerOf(Option<AccountIdOf<T>>),
	/// Attribute value of a specified collection item.
	GetAttribute(Option<Vec<u8>>),
	/// Details of a specified collection.
	Collection(Option<CollectionDetailsFor<T>>),
	/// Next collection ID.
	NextCollectionId(Option<CollectionIdOf<T>>),
	/// Metadata of a specified collection item.
	ItemMetadata(Option<Vec<u8>>),
}

[chungquantin]

Could this parameter be changed to Vec and we handle the length check in the runtime, so contract api implementation does not need to handle it?

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 91.83673% with 116 lines in your changes missing coverage. Please review.

Project coverage is 73.05%. Comparing base (663066e) to head (80fe5f3).

Files with missing lines	Patch %	Lines
pallets/api/src/nonfungibles/weights.rs	50.00%	64 Missing ⚠️
pallets/api/src/nonfungibles/mod.rs	84.51%	19 Missing and 5 partials ⚠️
pallets/api/src/mock.rs	8.69%	21 Missing ⚠️
pallets/api/src/nonfungibles/benchmarking.rs	0.00%	5 Missing ⚠️
pallets/api/src/nonfungibles/tests.rs	99.81%	1 Missing and 1 partial ⚠️

@@                      Coverage Diff                       @@
##           frank/nfts-balance-deposit     #388      +/-   ##
==============================================================
+ Coverage                       70.65%   73.05%   +2.39%     
==============================================================
  Files                              72       77       +5     
  Lines                           13207    14628    +1421     
  Branches                        13207    14628    +1421     
==============================================================
+ Hits                             9332    10686    +1354     
- Misses                           3604     3672      +68     
+ Partials                          271      270       -1     

Files with missing lines	Coverage Δ
pallets/api/src/nonfungibles/impls.rs	100.00% <100.00%> (ø)
pallets/api/src/nonfungibles/tests.rs	99.81% <99.81%> (ø)
pallets/api/src/nonfungibles/benchmarking.rs	0.00% <0.00%> (ø)
pallets/api/src/mock.rs	55.31% <8.69%> (-44.69%)	⬇️
pallets/api/src/nonfungibles/mod.rs	84.51% <84.51%> (ø)
pallets/api/src/nonfungibles/weights.rs	50.00% <50.00%> (ø)

... and 6 files with indirect coverage changes