unc-contract-standards 2.3.2

Utility smart contracts standard library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

use unc_sdk::ext_contract;
use unc_sdk::json_types::U128;
use unc_sdk::AccountId;
use unc_sdk::PromiseOrValue;
/// The core methods for a basic fungible token. Extension standards may be
/// added in addition to this trait.
///
/// # Examples
///
/// ```
/// use unc_sdk::{unc, PanicOnDefault, AccountId, PromiseOrValue};
/// use unc_sdk::collections::LazyOption;
/// use unc_sdk::json_types::U128;
/// use unc_contract_standards::fungible_token::{FungibleToken, FungibleTokenCore};
/// use unc_contract_standards::fungible_token::metadata::FungibleTokenMetadata;
///
/// #[unc(contract_state)]
/// #[derive(PanicOnDefault)]
/// pub struct Contract {
///     token: FungibleToken,
///     metadata: LazyOption<FungibleTokenMetadata>,
/// }
///
/// #[unc]
/// impl FungibleTokenCore for Contract {
///     #[payable]
///     fn ft_transfer(&mut self, receiver_id: AccountId, amount: U128, memo: Option<String>) {
///         self.token.ft_transfer(receiver_id, amount, memo)
///     }
///
///     #[payable]
///     fn ft_transfer_call(
///         &mut self,
///         receiver_id: AccountId,
///         amount: U128,
///         memo: Option<String>,
///         msg: String,
///     ) -> PromiseOrValue<U128> {
///         self.token.ft_transfer_call(receiver_id, amount, memo, msg)
///     }
///
///     fn ft_total_supply(&self) -> U128 {
///         self.token.ft_total_supply()
///     }
///
///     fn ft_balance_of(&self, account_id: AccountId) -> U128 {
///         self.token.ft_balance_of(account_id)
///     }
/// }
/// ```
///
#[ext_contract(ext_ft_core)]
pub trait FungibleTokenCore {
    /// Transfers positive `amount` of tokens from the `env::predecessor_account_id` to `receiver_id`.
    /// Both accounts must be registered with the contract for transfer to succeed. (See [UIP-145](https://github.com/utnet-org/UIPs/discussions/145))
    /// This method must to be able to accept attached deposits, and must not panic on attached deposit.
    /// Exactly 1 attoUNC must be attached.
    /// See [the Security section](https://github.com/utnet-org/UIPs/issues/141#user-content-security) of the standard.
    ///
    /// Arguments:
    /// - `receiver_id` - the account ID of the receiver.
    /// - `amount` - the amount of tokens to transfer. Must be a positive number in decimal string representation.
    /// - `memo` - an optional string field in a free form to associate a memo with this transfer.
    fn ft_transfer(&mut self, receiver_id: AccountId, amount: U128, memo: Option<String>);

    /// Transfers positive `amount` of tokens from the `env::predecessor_account_id` to `receiver_id` account. Then
    /// calls `ft_on_transfer` method on `receiver_id` contract and attaches a callback to resolve this transfer.
    /// `ft_on_transfer` method must return the amount of tokens unused by the receiver contract, the remaining tokens
    /// must be refunded to the `predecessor_account_id` at the resolve transfer callback.
    ///
    /// Token contract must pass all the remaining unused gas to the `ft_on_transfer` call.
    ///
    /// Malicious or invalid behavior by the receiver's contract:
    /// - If the receiver contract promise fails or returns invalid value, the full transfer amount must be refunded.
    /// - If the receiver contract overspent the tokens, and the `receiver_id` balance is lower than the required refund
    /// amount, the remaining balance must be refunded. See [the Security section](https://github.com/utnet-org/UIPs/issues/141#user-content-security) of the standard.
    ///
    /// Both accounts must be registered with the contract for transfer to succeed. (See #145)
    /// This method must to be able to accept attached deposits, and must not panic on attached deposit. Exactly 1 attoUNC must be attached. See [the Security
    /// section](https://github.com/utnet-org/UIPs/issues/141#user-content-security) of the standard.
    ///
    /// Arguments:
    /// - `receiver_id` - the account ID of the receiver contract. This contract will be called.
    /// - `amount` - the amount of tokens to transfer. Must be a positive number in a decimal string representation.
    /// - `memo` - an optional string field in a free form to associate a memo with this transfer.
    /// - `msg` - a string message that will be passed to `ft_on_transfer` contract call.
    ///
    /// Returns a promise which will result in the amount of tokens withdrawn from sender's account.
    fn ft_transfer_call(
        &mut self,
        receiver_id: AccountId,
        amount: U128,
        memo: Option<String>,
        msg: String,
    ) -> PromiseOrValue<U128>;

    /// Returns the total supply of the token in a decimal string representation.
    fn ft_total_supply(&self) -> U128;

    /// Returns the balance of the account. If the account doesn't exist must returns `"0"`.
    fn ft_balance_of(&self, account_id: AccountId) -> U128;
}