iota_json_rpc_api/
coin.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use iota_json_rpc_types::{Balance, CoinPage, IotaCirculatingSupply, IotaCoinMetadata};
6use iota_open_rpc_macros::open_rpc;
7use iota_types::{
8    balance::Supply,
9    base_types::{IotaAddress, ObjectID},
10};
11use jsonrpsee::{core::RpcResult, proc_macros::rpc};
12
13/// Provides access to coin-related data such as coins owned by an address,
14/// balances, or metadata.
15#[open_rpc(namespace = "iotax", tag = "Coin Query API")]
16#[rpc(server, client, namespace = "iotax")]
17pub trait CoinReadApi {
18    /// Return all Coin<`coin_type`> objects owned by an address.
19    #[rustfmt::skip]
20    #[method(name = "getCoins")]
21    async fn get_coins(
22        &self,
23        /// the owner's IOTA address
24        owner: IotaAddress,
25        /// optional type name for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), default to 0x2::iota::IOTA if not specified.
26        coin_type: Option<String>,
27        /// optional paging cursor
28        cursor: Option<ObjectID>,
29        /// maximum number of items per page
30        limit: Option<usize>,
31    ) -> RpcResult<CoinPage>;
32
33    /// Return all Coin objects owned by an address.
34    #[rustfmt::skip]
35    #[method(name = "getAllCoins")]
36    async fn get_all_coins(
37        &self,
38        /// the owner's IOTA address
39        owner: IotaAddress,
40        /// optional paging cursor
41        cursor: Option<ObjectID>,
42        /// maximum number of items per page
43        limit: Option<usize>,
44    ) -> RpcResult<CoinPage>;
45
46    /// Return the total coin balance for one coin type, owned by the address owner.
47    #[rustfmt::skip]
48    #[method(name = "getBalance")]
49    async fn get_balance(
50        &self,
51        /// the owner's IOTA address
52        owner: IotaAddress,
53        /// optional type names for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), default to 0x2::iota::IOTA if not specified.
54        coin_type: Option<String>,
55    ) -> RpcResult<Balance>;
56
57    /// Return the total coin balance for all coin type, owned by the address owner.
58    #[rustfmt::skip]
59    #[method(name = "getAllBalances")]
60    async fn get_all_balances(
61        &self,
62        /// the owner's IOTA address
63        owner: IotaAddress,
64    ) -> RpcResult<Vec<Balance>>;
65
66    /// Return metadata (e.g., symbol, decimals) for a coin.
67    #[rustfmt::skip]
68    #[method(name = "getCoinMetadata")]
69    async fn get_coin_metadata(
70        &self,
71        /// type name for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC)
72        coin_type: String,
73    ) -> RpcResult<Option<IotaCoinMetadata>>;
74
75    /// Return total supply for a coin.
76    #[rustfmt::skip]
77    #[method(name = "getTotalSupply")]
78    async fn get_total_supply(
79        &self,
80        /// type name for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC)
81        coin_type: String,
82    ) -> RpcResult<Supply>;
83
84    /// Return the circulating supply summary.
85    #[method(name = "getCirculatingSupply")]
86    async fn get_circulating_supply(&self) -> RpcResult<IotaCirculatingSupply>;
87}
iota_json_rpc_api/coin.rs

iota_json_rpc_api/
coin.rs
