casper_client/cli/payment_str_params.rs
1#[cfg(doc)]
2use crate::cli;
3
4/// Container for payment-related arguments used while constructing a `Deploy`.
5///
6/// ## `payment_args_simple`
7///
8/// For methods taking `payment_args_simple`, this parameter is the payment contract arguments, in
9/// the form `<NAME:TYPE='VALUE'>` or `<NAME:TYPE=null>`.
10///
11/// It can only be used with the following simple `CLType`s: bool, i32, i64, u8, u32, u64, u128,
12/// u256, u512, unit, string, key, account_hash, uref, public_key and `Option` of each of these.
13///
14/// Example inputs are:
15///
16/// ```text
17/// name_01:bool='false'
18/// name_02:i32='-1'
19/// name_03:i64='-2'
20/// name_04:u8='3'
21/// name_05:u32='4'
22/// name_06:u64='5'
23/// name_07:u128='6'
24/// name_08:u256='7'
25/// name_09:u512='8'
26/// name_10:unit=''
27/// name_11:string='a value'
28/// key_account_name:key='account-hash-0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20'
29/// key_hash_name:key='hash-0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20'
30/// key_uref_name:key='uref-0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20-000'
31/// account_hash_name:account_hash='account-hash-0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20'
32/// uref_name:uref='uref-0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20-007'
33/// public_key_name:public_key='0119bf44096984cdfe8541bac167dc3b96c85086aa30b6b6cb0c5c38ad703166e1'
34/// ```
35///
36/// For optional values of any these types, prefix the type with "opt_" and use the term "null"
37/// without quotes to specify a None value:
38///
39/// ```text
40/// name_01:opt_bool='true' # Some(true)
41/// name_02:opt_bool='false' # Some(false)
42/// name_03:opt_bool=null # None
43/// name_04:opt_i32='-1' # Some(-1)
44/// name_05:opt_i32=null # None
45/// name_06:opt_unit='' # Some(())
46/// name_07:opt_unit=null # None
47/// name_08:opt_string='a value' # Some("a value".to_string())
48/// name_09:opt_string='null' # Some("null".to_string())
49/// name_10:opt_string=null # None
50/// ```
51///
52/// To get a list of supported types, call [`cli::simple_args_help::supported_cl_type_list`]. To
53/// get this list of examples for supported types, call
54/// [`cli::simple_args_help::supported_cl_type_examples`].
55///
56/// ## `payment_args_json`
57///
58/// For methods taking `payment_args_json`, this parameter is the payment contract arguments, as a
59/// JSON-encoded Array of JSON Objects of the form:
60/// ```json
61/// [{"name":<String>,"type":<VALUE>,"value":<VALUE>}]
62/// ```
63///
64/// To get comprehensive information and a set of examples, call
65/// [`cli::json_args_help::info_and_examples`].
66///
67/// Example inputs are:
68///
69/// ```json
70/// [{"name":"a","type":"Bool","value":false}]
71/// [{"name":"b","type":"I32","value":-1}]
72/// [{"name":"c","type":"U64","value":1}]
73/// [{"name":"d","type":"U512","value":"20000000000000000000"}]
74/// [{"name":"e","type":"Unit","value":null}]
75/// [{"name":"f","type":"String","value":"a"}]
76/// [{"name":"g","type":"Key","value":"account-hash-201f1e1d1c1b1a191817161514131211100f0e0d0c0b0a090807060504030201"}]
77/// [{"name":"h","type":"URef","value":"uref-201f1e1d1c1b1a191817161514131211100f0e0d0c0b0a090807060504030201-007"}]
78/// [{"name":"i","type":"PublicKey","value":"017279ea868d185a40ed32ec076807c070de9c0fe986f5418c2aa71478f1e8ddf8"}]
79/// [{"name":"j","type":{"Option":"U64"},"value":999}] # Some(999_u64)
80/// [{"name":"k","type":{"Option":"String"},"value":null}] # None
81/// [{"name":"l","type":{"List":{"Option":"U256"}},"value":[1,null,"3"]}]
82/// [{"name":"m","type":{"List":"U8"},"value":"0102ff"}] # for Vec<u8> only, can parse from hex string
83/// [{"name":"n","type":{"ByteArray":3},"value":"0114ff"}]
84/// [{"name":"o","type":{"ByteArray":3},"value":[1,20,255]}]
85/// [{"name":"p","type":{"Result":{"ok":"Bool","err":"U8"}},"value":{"Ok":true}}]
86/// [{"name":"q","type":{"Result":{"ok":"Bool","err":"U8"}},"value":{"Err":1}}]
87/// [{"name":"r","type":{"Map":{"key":"U8","value":"Bool"}},"value":[{"key":1,"value":true},{"key":2,"value":false}]}]
88/// ## for Map with key as String or Number can use an Object rather than an Array:
89/// [{"name":"s","type":{"Map":{"key":"U8","value":"Bool"}},"value":{"1":true,"2":false}}]
90/// [{"name":"t","type":{"Tuple3":["Bool","U8","String"]},"value":[true,128,"a"]}]
91/// ```
92///
93/// ## `payment_args_complex`
94///
95/// For methods taking `payment_args_complex`, this parameter is the payment contract arguments, in
96/// the form of a `ToBytes`-encoded file.
97///
98/// ---
99///
100/// **Note** while multiple payment args can be specified for a single payment code instance, only
101/// one of `payment_args_simple`, `payment_args_json` or `payment_args_complex` may be used.
102#[derive(Default)]
103pub struct PaymentStrParams<'a> {
104 pub(super) payment_amount: &'a str,
105 pub(super) payment_hash: &'a str,
106 pub(super) payment_name: &'a str,
107 pub(super) payment_package_hash: &'a str,
108 pub(super) payment_package_name: &'a str,
109 pub(super) payment_path: &'a str,
110 pub(super) payment_args_simple: Vec<&'a str>,
111 pub(super) payment_args_json: &'a str,
112 pub(super) payment_args_complex: &'a str,
113 pub(super) payment_version: &'a str,
114 pub(super) payment_entry_point: &'a str,
115}
116
117impl<'a> PaymentStrParams<'a> {
118 /// Constructs a `PaymentStrParams` using a payment smart contract file.
119 ///
120 /// * `payment_path` is the path to the compiled Wasm payment code.
121 /// * See the struct docs for a description of [`payment_args_simple`](#payment_args_simple),
122 /// [`payment_args_json`](#payment_args_json) and
123 /// [`payment_args_complex`](#payment_args_complex).
124 pub fn with_path(
125 payment_path: &'a str,
126 payment_args_simple: Vec<&'a str>,
127 payment_args_json: &'a str,
128 payment_args_complex: &'a str,
129 ) -> Self {
130 Self {
131 payment_path,
132 payment_args_simple,
133 payment_args_json,
134 payment_args_complex,
135 ..Default::default()
136 }
137 }
138
139 /// Constructs a `PaymentStrParams` using a payment amount.
140 ///
141 /// `payment_amount` uses the standard-payment system contract rather than custom payment Wasm.
142 /// The value is the 'amount' arg of the standard-payment contract.
143 pub fn with_amount(payment_amount: &'a str) -> Self {
144 Self {
145 payment_amount,
146 ..Default::default()
147 }
148 }
149
150 /// Constructs a `PaymentStrParams` using a stored contract's name.
151 ///
152 /// * `payment_name` is the name of the stored contract (associated with the executing account)
153 /// to be called as the payment.
154 /// * `payment_entry_point` is the name of the method that will be used when calling the payment
155 /// contract.
156 /// * See the struct docs for a description of [`payment_args_simple`](#payment_args_simple),
157 /// [`payment_args_json`](#payment_args_json) and
158 /// [`payment_args_complex`](#payment_args_complex).
159 pub fn with_name(
160 payment_name: &'a str,
161 payment_entry_point: &'a str,
162 payment_args_simple: Vec<&'a str>,
163 payment_args_json: &'a str,
164 payment_args_complex: &'a str,
165 ) -> Self {
166 Self {
167 payment_name,
168 payment_args_simple,
169 payment_args_json,
170 payment_args_complex,
171 payment_entry_point,
172 ..Default::default()
173 }
174 }
175
176 /// Constructs a `PaymentStrParams` using a stored contract's hex-encoded hash.
177 ///
178 /// * `payment_hash` is the hex-encoded hash of the stored contract to be called as the payment.
179 /// * `payment_entry_point` is the name of the method that will be used when calling the payment
180 /// contract.
181 /// * See the struct docs for a description of [`payment_args_simple`](#payment_args_simple),
182 /// [`payment_args_json`](#payment_args_json) and
183 /// [`payment_args_complex`](#payment_args_complex).
184 pub fn with_hash(
185 payment_hash: &'a str,
186 payment_entry_point: &'a str,
187 payment_args_simple: Vec<&'a str>,
188 payment_args_json: &'a str,
189 payment_args_complex: &'a str,
190 ) -> Self {
191 Self {
192 payment_hash,
193 payment_args_simple,
194 payment_args_json,
195 payment_args_complex,
196 payment_entry_point,
197 ..Default::default()
198 }
199 }
200
201 /// Constructs a `PaymentStrParams` using a stored contract's package name.
202 ///
203 /// * `payment_package_name` is the name of the stored package to be called as the payment.
204 /// * `payment_version` is the version of the called payment contract. The latest will be used
205 /// if `payment_version` is empty.
206 /// * `payment_entry_point` is the name of the method that will be used when calling the payment
207 /// contract.
208 /// * See the struct docs for a description of [`payment_args_simple`](#payment_args_simple),
209 /// [`payment_args_json`](#payment_args_json) and
210 /// [`payment_args_complex`](#payment_args_complex).
211 pub fn with_package_name(
212 payment_package_name: &'a str,
213 payment_version: &'a str,
214 payment_entry_point: &'a str,
215 payment_args_simple: Vec<&'a str>,
216 payment_args_json: &'a str,
217 payment_args_complex: &'a str,
218 ) -> Self {
219 Self {
220 payment_package_name,
221 payment_args_simple,
222 payment_args_json,
223 payment_args_complex,
224 payment_version,
225 payment_entry_point,
226 ..Default::default()
227 }
228 }
229
230 /// Constructs a `PaymentStrParams` using a stored contract's package hash.
231 ///
232 /// * `payment_package_hash` is the hex-encoded hash of the stored package to be called as the
233 /// payment.
234 /// * `payment_version` is the version of the called payment contract. The latest will be used
235 /// if `payment_version` is empty.
236 /// * `payment_entry_point` is the name of the method that will be used when calling the payment
237 /// contract.
238 /// * See the struct docs for a description of [`payment_args_simple`](#payment_args_simple),
239 /// [`payment_args_json`](#payment_args_json) and
240 /// [`payment_args_complex`](#payment_args_complex).
241 pub fn with_package_hash(
242 payment_package_hash: &'a str,
243 payment_version: &'a str,
244 payment_entry_point: &'a str,
245 payment_args_simple: Vec<&'a str>,
246 payment_args_json: &'a str,
247 payment_args_complex: &'a str,
248 ) -> Self {
249 Self {
250 payment_package_hash,
251 payment_args_simple,
252 payment_args_json,
253 payment_args_complex,
254 payment_version,
255 payment_entry_point,
256 ..Default::default()
257 }
258 }
259}