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

iota_json_rpc_api/
indexer.rs
