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 client. This mode
25    ///    is a proxy for transaction finality.
26    /// 2. WaitForLocalExecution: waits for TransactionEffectsCert and make sure the node executed
27    ///    the transaction locally before returning the client. The local execution makes sure this
28    ///    node is aware of this transaction when client fires subsequent queries. However if the
29    ///    node fails to execute the transaction locally in a timely manner, a bool type in the
30    ///    response is set to false to indicated the case.
31    /// request_type defaults to `WaitForEffectsCert` when omitted.
32    #[rustfmt::skip]
33    #[method(name = "executeTransactionBlock")]
34    async fn execute_transaction_block(
35        &self,
36        /// BCS serialized transaction data bytes without its type tag, as base-64 encoded string.
37        #[schemars(with = "Base64Schema")]
38        tx_bytes: Base64,
39        /// 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.
40        #[schemars(with = "Vec<Base64Schema>")]
41        signatures: Vec<Base64>,
42        /// options for specifying the content to be returned
43        options: Option<IotaTransactionBlockResponseOptions>,
44        /// The request type, `WaitForEffectsCert` if None
45        request_type: Option<ExecuteTransactionRequestType>,
46    ) -> RpcResult<IotaTransactionBlockResponse>;
47
48    /// Calls a Move view function. The function must be declared with the `#[view]`
49    /// attribute.
50    #[rustfmt::skip]
51    #[method(name = "view")]
52    async fn view_function_call(
53        &self,
54        /// The fully qualified function name `<package_id>::<module_name>::<function_name>`, where the function is declared with the `#[view]` attribute. E.g. `0x1234::counter::value`.
55        function_name: String,
56        #[schemars(with = "Option<Vec<TypeTagSchema>>")]
57        type_args: Option<Vec<IotaTypeTag>>,
58        arguments: Vec<IotaJsonValue>,
59    ) -> RpcResult<IotaMoveViewCallResults>;
60
61    /// Runs the transaction in dev-inspect mode. Which allows for nearly any
62    /// transaction (or Move call) with any arguments. Detailed results are
63    /// provided, including both the transaction effects and any return values.
64    #[rustfmt::skip]
65    #[method(name = "devInspectTransactionBlock")]
66    async fn dev_inspect_transaction_block(
67        &self,
68        #[schemars(with = "AddressSchema")]
69        sender_address: Address,
70        /// BCS encoded TransactionKind(as opposed to Transaction, which include gasBudget and gasPrice)
71        #[schemars(with = "Base64Schema")]
72        tx_bytes: Base64,
73        /// Gas is not charged, but gas usage is still calculated. Default to use reference gas price
74        #[schemars(with = "Option<String>")]
75        gas_price: Option<BigInt<u64>>,
76        /// The epoch to perform the call. Will be set from the system state object if not provided
77        #[schemars(with = "Option<String>")]
78        epoch: Option<BigInt<u64>>,
79        /// Additional arguments including gas_budget, gas_objects, gas_sponsor and skip_checks.
80        additional_args: Option<DevInspectArgs>,
81    ) -> RpcResult<DevInspectResults>;
82
83    /// Return transaction execution effects including the gas cost summary,
84    /// while the effects are not committed to the chain.
85    #[method(name = "dryRunTransactionBlock")]
86    async fn dry_run_transaction_block(
87        &self,
88        #[schemars(with = "Base64Schema")] tx_bytes: Base64,
89    ) -> RpcResult<DryRunTransactionBlockResponse>;
90}
iota_json_rpc_api/write.rs

iota_json_rpc_api/
write.rs
