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

iota_json_rpc_api/
indexer.rs
