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

// Copyright (c) Mysten Labs, Inc.
// Modifications Copyright (c) 2024 IOTA Stiftung
// SPDX-License-Identifier: Apache-2.0

use iota_json_rpc_types::{Balance, CoinPage, IotaCoinMetadata};
use iota_open_rpc_macros::open_rpc;
use iota_types::{
    balance::Supply,
    base_types::{IotaAddress, ObjectID},
};
use jsonrpsee::{core::RpcResult, proc_macros::rpc};

/// Provides access to coin-related data such as coins owned by an address,
/// balances, or metadata.
#[open_rpc(namespace = "iotax", tag = "Coin Query API")]
#[rpc(server, client, namespace = "iotax")]
pub trait CoinReadApi {
    /// Return all Coin<`coin_type`> objects owned by an address.
    #[rustfmt::skip]
    #[method(name = "getCoins")]
    async fn get_coins(
        &self,
        /// the owner's Iota address
        owner: IotaAddress,
        /// optional type name for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), default to 0x2::iota::IOTA if not specified.
        coin_type: Option<String>,
        /// optional paging cursor
        cursor: Option<ObjectID>,
        /// maximum number of items per page
        limit: Option<usize>,
    ) -> RpcResult<CoinPage>;

    /// Return all Coin objects owned by an address.
    #[rustfmt::skip]
    #[method(name = "getAllCoins")]
    async fn get_all_coins(
        &self,
        /// the owner's Iota address
        owner: IotaAddress,
        /// optional paging cursor
        cursor: Option<ObjectID>,
        /// maximum number of items per page
        limit: Option<usize>,
    ) -> RpcResult<CoinPage>;

    /// Return the total coin balance for one coin type, owned by the address owner.
    #[rustfmt::skip]
    #[method(name = "getBalance")]
    async fn get_balance(
        &self,
        /// the owner's Iota address
        owner: IotaAddress,
        /// optional type names for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), default to 0x2::iota::IOTA if not specified.
        coin_type: Option<String>,
    ) -> RpcResult<Balance>;

    /// Return the total coin balance for all coin type, owned by the address owner.
    #[rustfmt::skip]
    #[method(name = "getAllBalances")]
    async fn get_all_balances(
        &self,
        /// the owner's Iota address
        owner: IotaAddress,
    ) -> RpcResult<Vec<Balance>>;

    /// Return metadata (e.g., symbol, decimals) for a coin.
    #[rustfmt::skip]
    #[method(name = "getCoinMetadata")]
    async fn get_coin_metadata(
        &self,
        /// type name for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC)
        coin_type: String,
    ) -> RpcResult<Option<IotaCoinMetadata>>;

    /// Return total supply for a coin.
    #[rustfmt::skip]
    #[method(name = "getTotalSupply")]
    async fn get_total_supply(
        &self,
        /// type name for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC)
        coin_type: String,
    ) -> RpcResult<Supply>;
}