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