frame_support/traits/tokens/

nonfungibles_v2.rs

// This file is part of Substrate.

// Copyright (C) Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: Apache-2.0

// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// 	http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Traits for dealing with multiple collections of non-fungible items.
//!
//! This assumes a dual-level namespace identified by `Inspect::ItemId`, and could
//! reasonably be implemented by pallets which want to expose multiple independent collections of
//! NFT-like objects.
//!
//! For an NFT API which has single-level namespacing, the traits in `nonfungible` are better to
//! use.
//!
//! Implementations of these traits may be converted to implementations of corresponding
//! `nonfungible` traits by using the `nonfungible::ItemOf` type adapter.

use crate::dispatch::{DispatchResult, Parameter};
use alloc::vec::Vec;
use codec::{Decode, Encode};
use sp_runtime::{DispatchError, TokenError};

/// Trait for providing an interface to many read-only NFT-like sets of items.
pub trait Inspect<AccountId> {
	/// Type for identifying an item.
	type ItemId: Parameter;

	/// Type for identifying a collection (an identifier for an independent collection of
	/// items).
	type CollectionId: Parameter;

	/// Returns the owner of `item` of `collection`, or `None` if the item doesn't exist
	/// (or somehow has no owner).
	fn owner(collection: &Self::CollectionId, item: &Self::ItemId) -> Option<AccountId>;

	/// Returns the owner of the `collection`, if there is one. For many NFTs this may not
	/// make any sense, so users of this API should not be surprised to find a collection
	/// results in `None` here.
	fn collection_owner(_collection: &Self::CollectionId) -> Option<AccountId> {
		None
	}

	/// Returns the attribute value of `item` of `collection` corresponding to `key`.
	///
	/// By default this is `None`; no attributes are defined.
	fn attribute(
		_collection: &Self::CollectionId,
		_item: &Self::ItemId,
		_key: &[u8],
	) -> Option<Vec<u8>> {
		None
	}

	/// Returns the custom attribute value of `item` of `collection` corresponding to `key`.
	///
	/// By default this is `None`; no attributes are defined.
	fn custom_attribute(
		_account: &AccountId,
		_collection: &Self::CollectionId,
		_item: &Self::ItemId,
		_key: &[u8],
	) -> Option<Vec<u8>> {
		None
	}

	/// Returns the system attribute value of `item` of `collection` corresponding to `key` if
	/// `item` is `Some`. Otherwise, returns the system attribute value of `collection`
	/// corresponding to `key`.
	///
	/// By default this is `None`; no attributes are defined.
	fn system_attribute(
		_collection: &Self::CollectionId,
		_item: Option<&Self::ItemId>,
		_key: &[u8],
	) -> Option<Vec<u8>> {
		None
	}

	/// Returns the strongly-typed attribute value of `item` of `collection` corresponding to
	/// `key`.
	///
	/// By default this just attempts to use `attribute`.
	fn typed_attribute<K: Encode, V: Decode>(
		collection: &Self::CollectionId,
		item: &Self::ItemId,
		key: &K,
	) -> Option<V> {
		key.using_encoded(|d| Self::attribute(collection, item, d))
			.and_then(|v| V::decode(&mut &v[..]).ok())
	}

	/// Returns the strongly-typed custom attribute value of `item` of `collection` corresponding to
	/// `key`.
	///
	/// By default this just attempts to use `custom_attribute`.
	fn typed_custom_attribute<K: Encode, V: Decode>(
		account: &AccountId,
		collection: &Self::CollectionId,
		item: &Self::ItemId,
		key: &K,
	) -> Option<V> {
		key.using_encoded(|d| Self::custom_attribute(account, collection, item, d))
			.and_then(|v| V::decode(&mut &v[..]).ok())
	}

	/// Returns the strongly-typed system attribute value of `item` corresponding to `key` if
	/// `item` is `Some`. Otherwise, returns the strongly-typed system attribute value of
	/// `collection` corresponding to `key`.
	///
	/// By default this just attempts to use `system_attribute`.
	fn typed_system_attribute<K: Encode, V: Decode>(
		collection: &Self::CollectionId,
		item: Option<&Self::ItemId>,
		key: &K,
	) -> Option<V> {
		key.using_encoded(|d| Self::system_attribute(collection, item, d))
			.and_then(|v| V::decode(&mut &v[..]).ok())
	}

	/// Returns the attribute value of `collection` corresponding to `key`.
	///
	/// By default this is `None`; no attributes are defined.
	fn collection_attribute(_collection: &Self::CollectionId, _key: &[u8]) -> Option<Vec<u8>> {
		None
	}

	/// Returns the strongly-typed attribute value of `collection` corresponding to `key`.
	///
	/// By default this just attempts to use `collection_attribute`.
	fn typed_collection_attribute<K: Encode, V: Decode>(
		collection: &Self::CollectionId,
		key: &K,
	) -> Option<V> {
		key.using_encoded(|d| Self::collection_attribute(collection, d))
			.and_then(|v| V::decode(&mut &v[..]).ok())
	}

	/// Returns `true` if the `item` of `collection` may be transferred.
	///
	/// Default implementation is that all items are transferable.
	fn can_transfer(_collection: &Self::CollectionId, _item: &Self::ItemId) -> bool {
		true
	}
}

/// Interface for enumerating items in existence or owned by a given account over many collections
/// of NFTs.
pub trait InspectEnumerable<AccountId>: Inspect<AccountId> {
	/// The iterator type for [`Self::collections`].
	type CollectionsIterator: Iterator<Item = Self::CollectionId>;
	/// The iterator type for [`Self::items`].
	type ItemsIterator: Iterator<Item = Self::ItemId>;
	/// The iterator type for [`Self::owned`].
	type OwnedIterator: Iterator<Item = (Self::CollectionId, Self::ItemId)>;
	/// The iterator type for [`Self::owned_in_collection`].
	type OwnedInCollectionIterator: Iterator<Item = Self::ItemId>;

	/// Returns an iterator of the collections in existence.
	fn collections() -> Self::CollectionsIterator;

	/// Returns an iterator of the items of a `collection` in existence.
	fn items(collection: &Self::CollectionId) -> Self::ItemsIterator;

	/// Returns an iterator of the items of all collections owned by `who`.
	fn owned(who: &AccountId) -> Self::OwnedIterator;

	/// Returns an iterator of the items of `collection` owned by `who`.
	fn owned_in_collection(
		collection: &Self::CollectionId,
		who: &AccountId,
	) -> Self::OwnedInCollectionIterator;
}

/// Trait for providing an interface to check the account's role within the collection.
pub trait InspectRole<AccountId>: Inspect<AccountId> {
	/// Returns `true` if `who` is the issuer of the `collection`.
	fn is_issuer(collection: &Self::CollectionId, who: &AccountId) -> bool;
	/// Returns `true` if `who` is the admin of the `collection`.
	fn is_admin(collection: &Self::CollectionId, who: &AccountId) -> bool;
	/// Returns `true` if `who` is the freezer of the `collection`.
	fn is_freezer(collection: &Self::CollectionId, who: &AccountId) -> bool;
}

/// Trait for providing the ability to create collections of nonfungible items.
pub trait Create<AccountId, CollectionConfig>: Inspect<AccountId> {
	/// Create a `collection` of nonfungible items to be owned by `who` and managed by `admin`.
	fn create_collection(
		who: &AccountId,
		admin: &AccountId,
		config: &CollectionConfig,
	) -> Result<Self::CollectionId, DispatchError>;

	fn create_collection_with_id(
		collection: Self::CollectionId,
		who: &AccountId,
		admin: &AccountId,
		config: &CollectionConfig,
	) -> Result<(), DispatchError>;
}

/// Trait for providing the ability to destroy collections of nonfungible items.
pub trait Destroy<AccountId>: Inspect<AccountId> {
	/// The witness data needed to destroy an item.
	type DestroyWitness: Parameter;

	/// Provide the appropriate witness data needed to destroy an item.
	fn get_destroy_witness(collection: &Self::CollectionId) -> Option<Self::DestroyWitness>;

	/// Destroy an existing fungible item.
	/// * `collection`: The `CollectionId` to be destroyed.
	/// * `witness`: Any witness data that needs to be provided to complete the operation
	///   successfully.
	/// * `maybe_check_owner`: An optional `AccountId` that can be used to authorize the destroy
	///   command. If not provided, we will not do any authorization checks before destroying the
	///   item.
	///
	/// If successful, this function will return the actual witness data from the destroyed item.
	/// This may be different than the witness data provided, and can be used to refund weight.
	fn destroy(
		collection: Self::CollectionId,
		witness: Self::DestroyWitness,
		maybe_check_owner: Option<AccountId>,
	) -> Result<Self::DestroyWitness, DispatchError>;
}

/// Trait for providing an interface for multiple collections of NFT-like items which may be
/// minted, burned and/or have attributes and metadata set on them.
pub trait Mutate<AccountId, ItemConfig>: Inspect<AccountId> {
	/// Mint some `item` of `collection` to be owned by `who`.
	///
	/// By default, this is not a supported operation.
	fn mint_into(
		_collection: &Self::CollectionId,
		_item: &Self::ItemId,
		_who: &AccountId,
		_config: &ItemConfig,
		_deposit_collection_owner: bool,
	) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Burn some `item` of `collection`.
	///
	/// By default, this is not a supported operation.
	fn burn(
		_collection: &Self::CollectionId,
		_item: &Self::ItemId,
		_maybe_check_owner: Option<&AccountId>,
	) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Set attribute `value` of `item` of `collection`'s `key`.
	///
	/// By default, this is not a supported operation.
	fn set_attribute(
		_collection: &Self::CollectionId,
		_item: &Self::ItemId,
		_key: &[u8],
		_value: &[u8],
	) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Attempt to set the strongly-typed attribute `value` of `item` of `collection`'s `key`.
	///
	/// By default this just attempts to use `set_attribute`.
	fn set_typed_attribute<K: Encode, V: Encode>(
		collection: &Self::CollectionId,
		item: &Self::ItemId,
		key: &K,
		value: &V,
	) -> DispatchResult {
		key.using_encoded(|k| value.using_encoded(|v| Self::set_attribute(collection, item, k, v)))
	}

	/// Set attribute `value` of `collection`'s `key`.
	///
	/// By default, this is not a supported operation.
	fn set_collection_attribute(
		_collection: &Self::CollectionId,
		_key: &[u8],
		_value: &[u8],
	) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Attempt to set the strongly-typed attribute `value` of `collection`'s `key`.
	///
	/// By default this just attempts to use `set_attribute`.
	fn set_typed_collection_attribute<K: Encode, V: Encode>(
		collection: &Self::CollectionId,
		key: &K,
		value: &V,
	) -> DispatchResult {
		key.using_encoded(|k| {
			value.using_encoded(|v| Self::set_collection_attribute(collection, k, v))
		})
	}

	/// Set the metadata `data` of an `item` of `collection`.
	///
	/// By default, this is not a supported operation.
	fn set_item_metadata(
		_who: Option<&AccountId>,
		_collection: &Self::CollectionId,
		_item: &Self::ItemId,
		_data: &[u8],
	) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Set the metadata `data` of a `collection`.
	///
	/// By default, this is not a supported operation.
	fn set_collection_metadata(
		_who: Option<&AccountId>,
		_collection: &Self::CollectionId,
		_data: &[u8],
	) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Clear attribute of `item` of `collection`'s `key`.
	///
	/// By default, this is not a supported operation.
	fn clear_attribute(
		_collection: &Self::CollectionId,
		_item: &Self::ItemId,
		_key: &[u8],
	) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Attempt to clear the strongly-typed attribute of `item` of `collection`'s `key`.
	///
	/// By default this just attempts to use `clear_attribute`.
	fn clear_typed_attribute<K: Encode>(
		collection: &Self::CollectionId,
		item: &Self::ItemId,
		key: &K,
	) -> DispatchResult {
		key.using_encoded(|k| Self::clear_attribute(collection, item, k))
	}

	/// Clear attribute of `collection`'s `key`.
	///
	/// By default, this is not a supported operation.
	fn clear_collection_attribute(_collection: &Self::CollectionId, _key: &[u8]) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Attempt to clear the strongly-typed attribute of `collection`'s `key`.
	///
	/// By default this just attempts to use `clear_attribute`.
	fn clear_typed_collection_attribute<K: Encode>(
		collection: &Self::CollectionId,
		key: &K,
	) -> DispatchResult {
		key.using_encoded(|k| Self::clear_collection_attribute(collection, k))
	}

	/// Clear the metadata of an `item` of `collection`.
	///
	/// By default, this is not a supported operation.
	fn clear_item_metadata(
		_who: Option<&AccountId>,
		_collection: &Self::CollectionId,
		_item: &Self::ItemId,
	) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Clear the metadata of a `collection`.
	///
	/// By default, this is not a supported operation.
	fn clear_collection_metadata(
		_who: Option<&AccountId>,
		_collection: &Self::CollectionId,
	) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}
}

/// Trait for transferring non-fungible sets of items.
pub trait Transfer<AccountId>: Inspect<AccountId> {
	/// Transfer `item` of `collection` into `destination` account.
	fn transfer(
		collection: &Self::CollectionId,
		item: &Self::ItemId,
		destination: &AccountId,
	) -> DispatchResult;

	/// Disable the `item` of `collection` transfer.
	///
	/// By default, this is not a supported operation.
	fn disable_transfer(_collection: &Self::CollectionId, _item: &Self::ItemId) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}

	/// Re-enable the `item` of `collection` transfer.
	///
	/// By default, this is not a supported operation.
	fn enable_transfer(_collection: &Self::CollectionId, _item: &Self::ItemId) -> DispatchResult {
		Err(TokenError::Unsupported.into())
	}
}

/// Trait for trading non-fungible items.
pub trait Trading<AccountId, ItemPrice>: Inspect<AccountId> {
	/// Allows `buyer` to buy an `item` of `collection` if it's up for sale with a `bid_price` to
	/// pay.
	fn buy_item(
		collection: &Self::CollectionId,
		item: &Self::ItemId,
		buyer: &AccountId,
		bid_price: &ItemPrice,
	) -> DispatchResult;

	/// Sets the item price for `item` to make it available for sale.
	fn set_price(
		collection: &Self::CollectionId,
		item: &Self::ItemId,
		sender: &AccountId,
		price: Option<ItemPrice>,
		whitelisted_buyer: Option<AccountId>,
	) -> DispatchResult;

	/// Returns the item price of `item` or `None` if the item is not for sale.
	fn item_price(collection: &Self::CollectionId, item: &Self::ItemId) -> Option<ItemPrice>;
}