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

iota_json_rpc_api/
write.rs
