dip721_rs/
lib.rs

1//! # DIP721-rs
2//!
3//! [DIP721-rs](https://github.com/veeso/dip721-rs) is a Rust library which provides the trait, the interface and types for Canisters that implement the DIP721 standard.
4//!
5//! ## Get started
6//!
7//! Add the following to your `Cargo.toml`:
8//!
9//! ```toml
10//! [dependencies]
11//! dip721 = "0.1.0"
12//! ```
13//!
14//! ### Features
15//!
16//! - `ic-stable-structures` (**default**): enables `Storable` for DIP721 types.
17//!
18
19#![doc(html_playground_url = "https://play.rust-lang.org")]
20
21mod canister;
22mod data;
23mod event;
24
25use async_trait::async_trait;
26use candid::{Nat, Principal};
27pub use canister::{Metadata, NftError, Stats, SupportedInterface};
28pub use data::{GenericValue, TokenIdentifier, TokenMetadata};
29pub use event::TxEvent;
30
31#[async_trait]
32/// Represents the method a DIP721 canister must implement
33pub trait Dip721 {
34    /// Returns the Metadata of the NFT canister which includes custodians, logo, name, symbol.
35    fn dip721_metadata() -> Metadata;
36
37    /// Returns the Stats of the NFT canister which includes cycles, totalSupply, totalTransactions, totalUniqueHolders.
38    fn dip721_stats() -> Stats;
39
40    /// Returns the logo of the NFT contract as Base64 encoded text.
41    fn dip721_logo() -> Option<String>;
42
43    /// Sets the logo of the NFT canister. Base64 encoded text is recommended.
44    /// Caller must be the custodian of NFT canister.
45    fn dip721_set_logo(logo: String);
46
47    /// Returns the name of the NFT canister.
48    fn dip721_name() -> Option<String>;
49
50    /// Sets the name of the NFT contract.
51    /// Caller must be the custodian of NFT canister.
52    fn dip721_set_name(name: String);
53
54    /// Returns the symbol of the NFT contract.
55    fn dip721_symbol() -> Option<String>;
56
57    /// Set symbol
58    /// Caller must be the custodian of NFT canister.
59    fn dip721_set_symbol(symbol: String);
60
61    /// Returns a list of the canister custodians
62    fn dip721_custodians() -> Vec<Principal>;
63
64    /// Set canister custodians
65    /// Caller must be the custodian of NFT canister.
66    fn dip721_set_custodians(custodians: Vec<Principal>);
67
68    /// Returns canister cycles
69    fn dip721_cycles() -> Nat;
70
71    /// Returns total unique holders of tokens
72    fn dip721_total_unique_holders() -> Nat;
73
74    /// Returns metadata for token
75    fn dip721_token_metadata(token_identifier: TokenIdentifier) -> Result<TokenMetadata, NftError>;
76
77    /// Returns the count of NFTs owned by user.
78    /// If the user does not own any NFTs, returns an error containing NftError.
79    fn dip721_balance_of(owner: Principal) -> Result<Nat, NftError>;
80
81    /// Returns the owner of the token.
82    /// Returns an error containing NftError if token_identifier is invalid.
83    fn dip721_owner_of(token_identifier: TokenIdentifier) -> Result<Option<Principal>, NftError>;
84
85    /// Returns the list of the token_identifier of the NFT associated with owner.
86    /// Returns an error containing NftError if principal is invalid.
87    fn dip721_owner_token_identifiers(owner: Principal) -> Result<Vec<TokenIdentifier>, NftError>;
88
89    /// Returns the list of the token_metadata of the NFT associated with owner.
90    /// Returns an error containing NftError if principal is invalid.
91    fn dip721_owner_token_metadata(owner: Principal) -> Result<Vec<TokenMetadata>, NftError>;
92
93    /// Returns the Principal of the operator of the NFT associated with token_identifier.
94    fn dip721_operator_of(token_identifier: TokenIdentifier)
95        -> Result<Option<Principal>, NftError>;
96
97    /// Returns the list of the token_identifier of the NFT associated with operator.
98    fn dip721_operator_token_identifiers(
99        operator: Principal,
100    ) -> Result<Vec<TokenIdentifier>, NftError>;
101
102    /// Returns the list of the token_metadata of the NFT associated with operator.
103    fn dip721_operator_token_metadata(operator: Principal) -> Result<Vec<TokenMetadata>, NftError>;
104
105    /// Returns the list of the interfaces supported by this canister
106    fn dip721_supported_interfaces() -> Vec<SupportedInterface>;
107
108    /// Returns the total supply of the NFT.
109    /// NFTs that are minted and later burned explicitly or sent to the zero address should also count towards totalSupply.
110    fn dip721_total_supply() -> Nat;
111
112    // Calling approve grants the operator the ability to make update calls to the specificied token_identifier.
113    // Approvals given by the approve function are independent from approvals given by the setApprovalForAll.
114    //
115    // If the approval goes through, returns a nat that represents the CAP History transaction ID that can be used at the transaction method.
116    /// Interface: approval
117    fn dip721_approve(
118        operator: Principal,
119        token_identifier: TokenIdentifier,
120    ) -> Result<Nat, NftError>;
121
122    /// Enable or disable an operator to manage all of the tokens for the caller of this function. The contract allows multiple operators per owner.
123    /// Approvals granted by the approve function are independent from the approvals granted by setApprovalForAll function.
124    /// If the approval goes through, returns a nat that represents the CAP History transaction ID that can be used at the transaction method.
125    /// Interface: approval
126    fn dip721_set_approval_for_all(operator: Principal, approved: bool) -> Result<Nat, NftError>;
127
128    /// Returns true if the given operator is an approved operator for all the tokens owned by the caller through the use of the setApprovalForAll method, returns false otherwise.
129    /// Interface: approval
130    fn dip721_is_approved_for_all(owner: Principal, operator: Principal) -> Result<bool, NftError>;
131
132    /// Sends the callers nft token_identifier to `to`` and returns a nat that represents a
133    /// transaction id that can be used at the transaction method.
134    async fn dip721_transfer(
135        to: Principal,
136        token_identifier: TokenIdentifier,
137    ) -> Result<Nat, NftError>;
138
139    /// Caller of this method is able to transfer the NFT token_identifier that is in from's balance to to's balance if the caller is an approved operator to do so.
140    ///
141    /// If the transfer goes through, returns a nat that represents the CAP History transaction ID that can be used at the transaction method.
142    async fn dip721_transfer_from(
143        owner: Principal,
144        to: Principal,
145        token_identifier: TokenIdentifier,
146    ) -> Result<Nat, NftError>;
147
148    /// Mint an NFT for principal to that has an ID of token_identifier and metadata akin to properties. Implementations are encouraged to only allow minting by the owner of the canister.
149    /// If the mint goes through, returns a nat that represents the CAP History transaction ID that can be used at the transaction method.
150    ///
151    /// Interface: mint
152    fn dip721_mint(
153        to: Principal,
154        token_identifier: TokenIdentifier,
155        properties: Vec<(String, GenericValue)>,
156    ) -> Result<Nat, NftError>;
157
158    /// Burn an NFT identified by token_identifier. Calling burn on a token sets the owner to None and will no longer be useable. Burned tokens do still count towards totalSupply.
159    /// Implementations are encouraged to only allow burning by the owner of the token_identifier.
160    fn dip721_burn(token_identifier: TokenIdentifier) -> Result<Nat, NftError>;
161
162    /// Returns the TxEvent that corresponds with tx_id.
163    /// If there is no TxEvent that corresponds with the tx_id entered, returns a NftError.TxNotFound.
164    fn dip721_transaction(tx_id: Nat) -> Result<TxEvent, NftError>;
165
166    /// Returns a nat that represents the total number of transactions that have occurred on the NFT canister.
167    fn dip721_total_transactions() -> Nat;
168}
dip721_rs/lib.rs

dip721_rs/
lib.rs
