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::{
6    Balance, Coin, CoinPage, IotaCirculatingSupply, IotaCoinMetadata, IotaSupply, Page,
7    iota_primitives::{IotaAddress as IotaAddressSchema, ObjectID as ObjectIDSchema},
8};
9use iota_open_rpc_macros::open_rpc;
10use iota_types::base_types::{IotaAddress, ObjectID};
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    #[schemars(with = "Page<Coin, ObjectIDSchema>")]
22    async fn get_coins(
23        &self,
24        /// the owner's IOTA address
25        #[schemars(with = "IotaAddressSchema")]
26        owner: IotaAddress,
27        /// optional type name for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), default to 0x2::iota::IOTA if not specified.
28        coin_type: Option<String>,
29        /// optional paging cursor
30        #[schemars(with = "Option<ObjectIDSchema>")]
31        cursor: Option<ObjectID>,
32        /// maximum number of items per page
33        limit: Option<usize>,
34    ) -> RpcResult<CoinPage>;
35
36    /// Return all Coin objects owned by an address.
37    #[rustfmt::skip]
38    #[method(name = "getAllCoins")]
39    #[schemars(with = "Page<Coin, ObjectIDSchema>")]
40    async fn get_all_coins(
41        &self,
42        /// the owner's IOTA address
43        #[schemars(with = "IotaAddressSchema")]
44        owner: IotaAddress,
45        /// optional paging cursor
46        #[schemars(with = "Option<ObjectIDSchema>")]
47        cursor: Option<ObjectID>,
48        /// maximum number of items per page
49        limit: Option<usize>,
50    ) -> RpcResult<CoinPage>;
51
52    /// Return the total coin balance for one coin type, owned by the address owner.
53    #[rustfmt::skip]
54    #[method(name = "getBalance")]
55    async fn get_balance(
56        &self,
57        /// the owner's IOTA address
58        #[schemars(with = "IotaAddressSchema")]
59        owner: IotaAddress,
60        /// optional type names for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), default to 0x2::iota::IOTA if not specified.
61        coin_type: Option<String>,
62    ) -> RpcResult<Balance>;
63
64    /// Return the total coin balance for all coin type, owned by the address owner.
65    #[rustfmt::skip]
66    #[method(name = "getAllBalances")]
67    async fn get_all_balances(
68        &self,
69        /// the owner's IOTA address
70        #[schemars(with = "IotaAddressSchema")]
71        owner: IotaAddress,
72    ) -> RpcResult<Vec<Balance>>;
73
74    /// Return metadata (e.g., symbol, decimals) for a coin.
75    #[rustfmt::skip]
76    #[method(name = "getCoinMetadata")]
77    async fn get_coin_metadata(
78        &self,
79        /// type name for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC)
80        coin_type: String,
81    ) -> RpcResult<Option<IotaCoinMetadata>>;
82
83    /// Return total supply for a coin.
84    #[rustfmt::skip]
85    #[method(name = "getTotalSupply")]
86    async fn get_total_supply(
87        &self,
88        /// type name for the coin (e.g., 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC)
89        coin_type: String,
90    ) -> RpcResult<IotaSupply>;
91
92    /// Return the circulating supply summary.
93    #[method(name = "getCirculatingSupply")]
94    async fn get_circulating_supply(&self) -> RpcResult<IotaCirculatingSupply>;
95}
iota_json_rpc_api/coin.rs

iota_json_rpc_api/
coin.rs
