iota_json_rpc_api/
indexer.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    DynamicFieldNameSchema, DynamicFieldPage, EventFilter, EventPage, IotaDynamicFieldInfo,
7    IotaEvent, IotaEventID, IotaNameRecord, IotaObjectDataOptions, IotaObjectResponse,
8    IotaObjectResponseQuery, IotaTransactionBlockEffects, IotaTransactionBlockResponse,
9    IotaTransactionBlockResponseQuery, IotaTransactionBlockResponseQueryV2, ObjectsPage, Page,
10    TransactionBlocksPage, TransactionFilter,
11    iota_primitives::{
12        Address as AddressSchema, Base58 as Base58Schema, ObjectId as ObjectIdSchema,
13    },
14};
15use iota_open_rpc_macros::open_rpc;
16use iota_sdk_types::{Address, ObjectId, TransactionDigest};
17use iota_types::{dynamic_field::DynamicFieldName, event::EventID};
18use jsonrpsee::{
19    core::{RpcResult, SubscriptionResult},
20    proc_macros::rpc,
21};
22
23/// Provides methods to query transactions, events, or objects and allows to
24/// subscribe to data streams.
25#[open_rpc(namespace = "iotax", tag = "Extended API")]
26#[rpc(server, client, namespace = "iotax")]
27pub trait IndexerApi {
28    /// Return the list of objects owned by an address.
29    /// Note that if the address owns more than `QUERY_MAX_RESULT_LIMIT` objects,
30    /// the pagination is not accurate, because previous page may have been updated
31    /// when the next page is fetched.
32    /// Please use iotax_queryObjects if this is a concern.
33    #[rustfmt::skip]
34    #[method(name = "getOwnedObjects")]
35    #[schemars(with = "Page<IotaObjectResponse, ObjectIdSchema>")]
36    async fn get_owned_objects(
37        &self,
38        /// the owner's IOTA address
39        #[schemars(with = "AddressSchema")] 
40        address: Address,
41        /// the objects query criteria.
42        query: Option<IotaObjectResponseQuery>,
43        /// An optional paging cursor. If provided, the query will start from the next item after the specified cursor. Default to start from the first item if not specified.
44        #[schemars(with = "Option<ObjectIdSchema>")] 
45        cursor: Option<ObjectId>,
46        /// Max number of items returned per page, default to [QUERY_MAX_RESULT_LIMIT] if not specified.
47        limit: Option<usize>,
48    ) -> RpcResult<ObjectsPage>;
49
50    /// Return list of transactions for a specified query criteria.
51    #[rustfmt::skip]
52    #[method(name = "queryTransactionBlocks", version <= "1.2.10")]
53    #[schemars(with = "Page<IotaTransactionBlockResponse, Base58>")]
54    async fn query_transaction_blocks(
55        &self,
56        /// the transaction query criteria.
57        query: IotaTransactionBlockResponseQuery,
58        /// An optional paging cursor. If provided, the query will start from the next item after the specified cursor. Default to start from the first item if not specified.
59        cursor: Option<TransactionDigest>,
60        /// Maximum item returned per page, default to QUERY_MAX_RESULT_LIMIT if not specified.
61        limit: Option<usize>,
62        /// query result ordering, default to false (ascending order), oldest record first.
63        descending_order: Option<bool>,
64    ) -> RpcResult<TransactionBlocksPage>;
65
66    /// Return list of transactions for a specified query criteria.
67    #[rustfmt::skip]
68    #[method(name = "queryTransactionBlocks")]
69    #[schemars(with = "Page<IotaTransactionBlockResponse, Base58Schema>")]
70    async fn query_transaction_blocks_v2(
71        &self,
72        /// the transaction query criteria.
73        query: IotaTransactionBlockResponseQueryV2,
74        /// An optional paging cursor. If provided, the query will start from the next item after the specified cursor. Default to start from the first item if not specified.
75        #[schemars(with = "Option<Base58Schema>")]
76        cursor: Option<TransactionDigest>,
77        /// Maximum item returned per page, default to QUERY_MAX_RESULT_LIMIT if not specified.
78        limit: Option<usize>,
79        /// query result ordering, default to false (ascending order), oldest record first.
80        descending_order: Option<bool>,
81    ) -> RpcResult<TransactionBlocksPage>;
82
83    /// Return list of events for a specified query criteria.
84    #[rustfmt::skip]
85    #[method(name = "queryEvents")]
86    #[schemars(with = "Page<IotaEvent, IotaEventID>")]
87    async fn query_events(
88        &self,
89        /// The event query criteria. See [Event filter](https://docs.iota.org/developer/iota-101/using-events#applying-event-filters) documentation for examples.
90        query: EventFilter,
91        /// optional paging cursor
92        #[schemars(with = "Option<IotaEventID>")]
93        cursor: Option<EventID>,
94        /// maximum number of items per page, default to [QUERY_MAX_RESULT_LIMIT] if not specified.
95        limit: Option<usize>,
96        /// query result ordering, default to false (ascending order), oldest record first.
97        descending_order: Option<bool>,
98    ) -> RpcResult<EventPage>;
99
100    /// Subscribe to a stream of IOTA event
101    #[rustfmt::skip]
102    #[subscription(name = "subscribeEvent", item = IotaEvent)]
103    fn subscribe_event(
104        &self,
105        /// The filter criteria of the event stream. See [Event filter](https://docs.iota.org/developer/iota-101/using-events#applying-event-filters) documentation for examples.
106        filter: EventFilter,
107    ) -> SubscriptionResult;
108
109    /// Subscribe to a stream of IOTA transaction effects
110    #[subscription(name = "subscribeTransaction", item = IotaTransactionBlockEffects)]
111    fn subscribe_transaction(&self, filter: TransactionFilter) -> SubscriptionResult;
112
113    /// Return the list of dynamic field objects owned by an object.
114    #[rustfmt::skip]
115    #[method(name = "getDynamicFields")]
116    #[schemars(with = "Page<IotaDynamicFieldInfo, ObjectIdSchema>")]
117    async fn get_dynamic_fields(
118        &self,
119        /// The ID of the parent object
120        #[schemars(with = "ObjectIdSchema")]
121        parent_object_id: ObjectId,
122        /// An optional paging cursor. If provided, the query will start from the next item after the specified cursor. Default to start from the first item if not specified.
123        #[schemars(with = "Option<ObjectIdSchema>")]
124        cursor: Option<ObjectId>,
125        /// Maximum item returned per page, default to [QUERY_MAX_RESULT_LIMIT] if not specified.
126        limit: Option<usize>,
127    ) -> RpcResult<DynamicFieldPage>;
128
129    /// Return the dynamic field object information for a specified object
130    #[rustfmt::skip]
131    #[method(name = "getDynamicFieldObject")]
132    async fn get_dynamic_field_object(
133        &self,
134        /// The ID of the queried parent object
135        #[schemars(with = "ObjectIdSchema")]
136        parent_object_id: ObjectId,
137        /// The Name of the dynamic field
138        #[schemars(with = "DynamicFieldNameSchema")]
139        name: DynamicFieldName,
140    ) -> RpcResult<IotaObjectResponse>;
141
142    /// Return the dynamic field object information for a specified object with
143    /// content options.
144    #[rustfmt::skip]
145    #[method(name = "getDynamicFieldObjectV2")]
146    async fn get_dynamic_field_object_v2(
147        &self,
148        /// The ID of the queried parent object
149        #[schemars(with = "ObjectIdSchema")]
150        parent_object_id: ObjectId,
151        /// The Name of the dynamic field
152        #[schemars(with = "DynamicFieldNameSchema")]
153        name: DynamicFieldName,
154        /// Options for specifying the content to be returned
155        options: Option<IotaObjectDataOptions>,
156    ) -> RpcResult<IotaObjectResponse>;
157
158    /// Return the resolved record for the given name.
159    #[method(name = "iotaNamesLookup")]
160    async fn iota_names_lookup(
161        &self,
162        /// The name to resolve
163        name: &str,
164    ) -> RpcResult<Option<IotaNameRecord>>;
165
166    /// Return the resolved name for the given address.
167    #[method(name = "iotaNamesReverseLookup")]
168    async fn iota_names_reverse_lookup(
169        &self,
170        /// The address to resolve.
171        #[schemars(with = "AddressSchema")]
172        address: Address,
173    ) -> RpcResult<Option<String>>;
174
175    /// Find all registration NFTs for the given address.
176    #[method(name = "iotaNamesFindAllRegistrationNFTs")]
177    #[schemars(with = "Page<IotaObjectResponse, ObjectIdSchema>")]
178    async fn iota_names_find_all_registration_nfts(
179        &self,
180        #[schemars(with = "AddressSchema")] address: Address,
181        #[schemars(with = "Option<ObjectIdSchema>")] cursor: Option<ObjectId>,
182        limit: Option<usize>,
183        options: Option<IotaObjectDataOptions>,
184    ) -> RpcResult<ObjectsPage>;
185}
iota_json_rpc_api/indexer.rs

iota_json_rpc_api/
indexer.rs
