iota_json_rpc_api/
write.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use fastcrypto::encoding::Base64;
6use iota_json::IotaJsonValue;
7use iota_json_rpc_types::{
8    DevInspectArgs, DevInspectResults, DryRunTransactionBlockResponse,
9    ExecuteTransactionRequestType, IotaMoveViewCallResults, IotaTransactionBlockResponse,
10    IotaTransactionBlockResponseOptions, IotaTypeTag,
11    iota_primitives::{Address as AddressSchema, Base64 as Base64Schema, TypeTag as TypeTagSchema},
12};
13use iota_open_rpc_macros::open_rpc;
14use iota_sdk_types::Address;
15use iota_types::iota_serde::BigInt;
16use jsonrpsee::{core::RpcResult, proc_macros::rpc};
17
18/// Provides methods for executing and testing transactions.
19#[open_rpc(namespace = "iota", tag = "Write API")]
20#[rpc(server, client, namespace = "iota")]
21pub trait WriteApi {
22    /// Execute the transaction and wait for results if desired.
23    /// Request types:
24    /// 1. WaitForEffectsCert: waits for TransactionEffectsCert and then return to
25    ///    client. This mode is a proxy for transaction finality.
26    /// 2. WaitForLocalExecution: waits for TransactionEffectsCert and make sure the
27    ///    node executed the transaction locally before returning the client. The
28    ///    local execution makes sure this node is aware of this transaction when
29    ///    client fires subsequent queries. However if the node fails to execute the
30    ///    transaction locally in a timely manner, a bool type in the response is
31    ///    set to false to indicated the case.
32    /// request_type is default to be `WaitForEffectsCert` unless
33    /// options.show_events or options.show_effects is true
34    #[rustfmt::skip]
35    #[method(name = "executeTransactionBlock")]
36    async fn execute_transaction_block(
37        &self,
38        /// BCS serialized transaction data bytes without its type tag, as base-64 encoded string.
39        #[schemars(with = "Base64Schema")]
40        tx_bytes: Base64,
41        /// A list of signatures (`flag || signature || pubkey` bytes, as base-64 encoded string). Signature is committed to the intent message of the transaction data, as base-64 encoded string.
42        #[schemars(with = "Vec<Base64Schema>")]
43        signatures: Vec<Base64>,
44        /// options for specifying the content to be returned
45        options: Option<IotaTransactionBlockResponseOptions>,
46        /// The request type, derived from `IotaTransactionBlockResponseOptions` if None
47        request_type: Option<ExecuteTransactionRequestType>,
48    ) -> RpcResult<IotaTransactionBlockResponse>;
49
50    /// Calls a move view function.
51    #[rustfmt::skip]
52    #[method(name = "view")]
53    async fn view_function_call(
54        &self,
55        /// The fully qualified function name `<package_id>::<module_name>::<function_name>`. E.g.  `0x3::iota_system::get_total_iota_supply`.
56        function_name: String,
57        #[schemars(with = "Option<Vec<TypeTagSchema>>")]
58        type_args: Option<Vec<IotaTypeTag>>,
59        arguments: Vec<IotaJsonValue>,
60    ) -> RpcResult<IotaMoveViewCallResults>;
61
62    /// Runs the transaction in dev-inspect mode. Which allows for nearly any
63    /// transaction (or Move call) with any arguments. Detailed results are
64    /// provided, including both the transaction effects and any return values.
65    #[rustfmt::skip]
66    #[method(name = "devInspectTransactionBlock")]
67    async fn dev_inspect_transaction_block(
68        &self,
69        #[schemars(with = "AddressSchema")]
70        sender_address: Address,
71        /// BCS encoded TransactionKind(as opposed to TransactionData, which include gasBudget and gasPrice)
72        #[schemars(with = "Base64Schema")]
73        tx_bytes: Base64,
74        /// Gas is not charged, but gas usage is still calculated. Default to use reference gas price
75        #[schemars(with = "Option<String>")]
76        gas_price: Option<BigInt<u64>>,
77        /// The epoch to perform the call. Will be set from the system state object if not provided
78        #[schemars(with = "Option<String>")]
79        epoch: Option<BigInt<u64>>,
80        /// Additional arguments including gas_budget, gas_objects, gas_sponsor and skip_checks.
81        additional_args: Option<DevInspectArgs>,
82    ) -> RpcResult<DevInspectResults>;
83
84    /// Return transaction execution effects including the gas cost summary,
85    /// while the effects are not committed to the chain.
86    #[method(name = "dryRunTransactionBlock")]
87    async fn dry_run_transaction_block(
88        &self,
89        #[schemars(with = "Base64Schema")] tx_bytes: Base64,
90    ) -> RpcResult<DryRunTransactionBlockResponse>;
91}
iota_json_rpc_api/write.rs

iota_json_rpc_api/
write.rs
