testnumbat_wasm/api/
send_api.rs

1use super::{BlockchainApi, ManagedTypeApi};
2use crate::types::{
3    BigUint, CodeMetadata, DcdtTokenPayment, ManagedAddress, ManagedArgBuffer, ManagedBuffer,
4    ManagedInto, ManagedVec, TokenIdentifier,
5};
6
7pub const DCDT_TRANSFER_STRING: &[u8] = b"DCDTTransfer";
8pub const DCDT_NFT_TRANSFER_STRING: &[u8] = b"DCDTNFTTransfer";
9pub const DCDT_MULTI_TRANSFER_STRING: &[u8] = b"MultiDCDTNFTTransfer";
10
11/// API that groups methods that either send REWA or DCDT, or that call other contracts.
12pub trait SendApi: ManagedTypeApi + BlockchainApi + Clone + Sized {
13    /// Sends REWA to a given address, directly.
14    /// Used especially for sending REWA to regular accounts.
15    fn direct_rewa<D>(&self, to: &ManagedAddress<Self>, amount: &BigUint<Self>, data: D)
16    where
17        D: ManagedInto<Self, ManagedBuffer<Self>>;
18
19    /// Sends REWA to an address (optionally) and executes like an async call, but without callback.
20    fn direct_rewa_execute(
21        &self,
22        to: &ManagedAddress<Self>,
23        amount: &BigUint<Self>,
24        gas_limit: u64,
25        endpoint_name: &ManagedBuffer<Self>,
26        arg_buffer: &ManagedArgBuffer<Self>,
27    ) -> Result<(), &'static [u8]>;
28
29    /// Sends DCDT to an address and executes like an async call, but without callback.
30    fn direct_dcdt_execute(
31        &self,
32        to: &ManagedAddress<Self>,
33        token: &TokenIdentifier<Self>,
34        amount: &BigUint<Self>,
35        gas_limit: u64,
36        endpoint_name: &ManagedBuffer<Self>,
37        arg_buffer: &ManagedArgBuffer<Self>,
38    ) -> Result<(), &'static [u8]>;
39
40    /// Sends DCDT NFT to an address and executes like an async call, but without callback.
41    #[allow(clippy::too_many_arguments)]
42    fn direct_dcdt_nft_execute(
43        &self,
44        to: &ManagedAddress<Self>,
45        token: &TokenIdentifier<Self>,
46        nonce: u64,
47        amount: &BigUint<Self>,
48        gas_limit: u64,
49        endpoint_name: &ManagedBuffer<Self>,
50        arg_buffer: &ManagedArgBuffer<Self>,
51    ) -> Result<(), &'static [u8]>;
52
53    fn direct_multi_dcdt_transfer_execute(
54        &self,
55        to: &ManagedAddress<Self>,
56        payments: &ManagedVec<Self, DcdtTokenPayment<Self>>,
57        gas_limit: u64,
58        endpoint_name: &ManagedBuffer<Self>,
59        arg_buffer: &ManagedArgBuffer<Self>,
60    ) -> Result<(), &'static [u8]>;
61
62    /// Sends an asynchronous call to another contract.
63    /// Calling this method immediately terminates tx execution.
64    /// Using it directly is generally discouraged.
65    ///
66    /// The data is expected to be of the form `functionName@<arg1-hex>@<arg2-hex>@...`.
67    /// Use a `HexCallDataSerializer` to prepare this field.
68    fn async_call_raw(
69        &self,
70        to: &ManagedAddress<Self>,
71        amount: &BigUint<Self>,
72        endpoint_name: &ManagedBuffer<Self>,
73        arg_buffer: &ManagedArgBuffer<Self>,
74    ) -> !;
75
76    /// Deploys a new contract in the same shard.
77    /// Unlike `async_call_raw`, the deployment is synchronous and tx execution continues afterwards.
78    /// Also unlike `async_call_raw`, it uses an argument buffer to pass arguments
79    /// If the deployment fails, Option::None is returned
80    fn deploy_contract(
81        &self,
82        gas: u64,
83        amount: &BigUint<Self>,
84        code: &ManagedBuffer<Self>,
85        code_metadata: CodeMetadata,
86        arg_buffer: &ManagedArgBuffer<Self>,
87    ) -> (ManagedAddress<Self>, ManagedVec<Self, ManagedBuffer<Self>>);
88
89    /// Deploys a new contract in the same shard by re-using the code of an already deployed source contract.
90    /// The deployment is done synchronously and the new contract's address is returned.
91    /// If the deployment fails, Option::None is returned
92    fn deploy_from_source_contract(
93        &self,
94        gas: u64,
95        amount: &BigUint<Self>,
96        source_contract_address: &ManagedAddress<Self>,
97        code_metadata: CodeMetadata,
98        arg_buffer: &ManagedArgBuffer<Self>,
99    ) -> (ManagedAddress<Self>, ManagedVec<Self, ManagedBuffer<Self>>);
100
101    /// Upgrades a child contract of the currently executing contract.
102    /// The upgrade is synchronous, and the current transaction will fail if the upgrade fails.
103    /// The child contract's new init function will be called with the provided arguments
104    fn upgrade_contract(
105        &self,
106        sc_address: &ManagedAddress<Self>,
107        gas: u64,
108        amount: &BigUint<Self>,
109        code: &ManagedBuffer<Self>,
110        code_metadata: CodeMetadata,
111        arg_buffer: &ManagedArgBuffer<Self>,
112    );
113
114    /// Same shard, in-line execution of another contract.
115    fn execute_on_dest_context_raw(
116        &self,
117        gas: u64,
118        address: &ManagedAddress<Self>,
119        value: &BigUint<Self>,
120        endpoint_name: &ManagedBuffer<Self>,
121        arg_buffer: &ManagedArgBuffer<Self>,
122    ) -> ManagedVec<Self, ManagedBuffer<Self>>;
123
124    /// Same shard, in-line execution of another contract.
125    /// Allows the contract to specify which result range to extract as sync call result.
126    /// This is a workaround to handle nested sync calls.
127    /// Please do not use this method unless there is absolutely no other option.
128    /// Will be eliminated after some future Andes hook redesign.
129    /// `range_closure` takes the number of results before, the number of results after,
130    /// and is expected to return the start index (inclusive) and end index (exclusive).
131    fn execute_on_dest_context_raw_custom_result_range<F>(
132        &self,
133        gas: u64,
134        address: &ManagedAddress<Self>,
135        value: &BigUint<Self>,
136        endpoint_name: &ManagedBuffer<Self>,
137        arg_buffer: &ManagedArgBuffer<Self>,
138        range_closure: F,
139    ) -> ManagedVec<Self, ManagedBuffer<Self>>
140    where
141        F: FnOnce(usize, usize) -> (usize, usize);
142
143    fn execute_on_dest_context_by_caller_raw(
144        &self,
145        gas: u64,
146        address: &ManagedAddress<Self>,
147        value: &BigUint<Self>,
148        endpoint_name: &ManagedBuffer<Self>,
149        arg_buffer: &ManagedArgBuffer<Self>,
150    ) -> ManagedVec<Self, ManagedBuffer<Self>>;
151
152    fn execute_on_same_context_raw(
153        &self,
154        gas: u64,
155        address: &ManagedAddress<Self>,
156        value: &BigUint<Self>,
157        endpoint_name: &ManagedBuffer<Self>,
158        arg_buffer: &ManagedArgBuffer<Self>,
159    ) -> ManagedVec<Self, ManagedBuffer<Self>>;
160
161    fn execute_on_dest_context_readonly_raw(
162        &self,
163        gas: u64,
164        address: &ManagedAddress<Self>,
165        endpoint_name: &ManagedBuffer<Self>,
166        arg_buffer: &ManagedArgBuffer<Self>,
167    ) -> ManagedVec<Self, ManagedBuffer<Self>>;
168
169    /// Used to store data between async call and callback.
170    fn storage_store_tx_hash_key(&self, data: &ManagedBuffer<Self>);
171
172    /// Used to store data between async call and callback.
173    fn storage_load_tx_hash_key(&self) -> ManagedBuffer<Self>;
174
175    /// Allows synchronously calling a local function by name. Execution is resumed afterwards.
176    /// You should never have to call this function directly.
177    /// Use the other specific methods instead.
178    fn call_local_dcdt_built_in_function(
179        &self,
180        gas: u64,
181        endpoint_name: &ManagedBuffer<Self>,
182        arg_buffer: &ManagedArgBuffer<Self>,
183    ) -> ManagedVec<Self, ManagedBuffer<Self>>;
184}
testnumbat_wasm/api/send_api.rs

testnumbat_wasm/api/
send_api.rs
