tx_info appendix revamp (#2017)

Closes #1439 ## Introduced changes  - ## Checklist  - [x] Linked relevant issue - [x] Updated relevant documentation - [x] Added relevant tests - [x] Performed self-review of the code - [x] Added changes to `CHANGELOG.md` --------- Co-authored-by: Kamil Jankowski <[email protected]>
foundry-rs · Apr 16, 2024 · 6df5d97 · 6df5d97
1 parent 289f740
commit 6df5d97
Show file tree

Hide file tree

Showing 8 changed files with 75 additions and 137 deletions.
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -49,14 +49,11 @@
  * [caller_address](appendix/cheatcodes/caller_address.md) 
  * [block_number](appendix/cheatcodes/block_number.md)
  * [block_timestamp](appendix/cheatcodes/block_timestamp.md)
+ * [tx_info](appendix/cheatcodes/tx_info.md)
  * [sequencer_address](appendix/cheatcodes/sequencer_address/README.md)
  * [elect](appendix/cheatcodes/sequencer_address/elect.md)
  * [start_elect](appendix/cheatcodes/sequencer_address/start_elect.md)
  * [stop_elect](appendix/cheatcodes/sequencer_address/stop_elect.md)
- * [tx_info](appendix/cheatcodes/tx_info/README.md)
- * [spoof](appendix/cheatcodes/tx_info/spoof.md)
- * [start_spoof](appendix/cheatcodes/tx_info/start_spoof.md)
- * [stop_spoof](appendix/cheatcodes/tx_info/stop_spoof.md)
  * [mock](appendix/cheatcodes/mock/README.md)
  * [mock_call](appendix/cheatcodes/mock/mock_call.md)
  * [start_mock_call](appendix/cheatcodes/mock/start_mock_call.md)

diff --git a/docs/src/appendix/cheatcodes.md b/docs/src/appendix/cheatcodes.md
@@ -14,9 +14,9 @@
 - [`elect`](cheatcodes/sequencer_address/elect.md) - changes the sequencer address for contracts, for a number of calls
 - [`start_elect`](cheatcodes/sequencer_address/start_elect.md) - changes the sequencer address for contracts
 - [`stop_elect`](cheatcodes/sequencer_address/stop_elect.md) - cancels the `elect` / `start_elect` for contracts
-- [`spoof`](cheatcodes/tx_info/spoof.md) - changes the transaction context for contracts, for a number of calls
-- [`start_spoof`](cheatcodes/tx_info/start_spoof.md) - changes the transaction context for contracts
-- [`stop_spoof`](cheatcodes/tx_info/stop_spoof.md) - cancels the `spoof` / `start_spoof` for contracts
+- [`spoof`](cheatcodes/tx_info#spoof) - changes the transaction context for contracts, for a number of calls
+- [`start_spoof`](cheatcodes/tx_info#start_spoof) - changes the transaction context for contracts
+- [`stop_spoof`](cheatcodes/tx_info#stop_spoof) - cancels the `spoof` / `start_spoof` for contracts
 - [`mock_call`](cheatcodes/mock/mock_call.md) - mocks a number of contract calls to an entry point
 - [`start_mock_call`](cheatcodes/mock/start_mock_call.md) - mocks contract call to an entry point
 - [`stop_mock_call`](cheatcodes/mock/stop_mock_call.md) - cancels the `mock_call` / `start_mock_call` for an entry point

diff --git a/docs/src/appendix/cheatcodes/tx_info.md b/docs/src/appendix/cheatcodes/tx_info.md
@@ -0,0 +1,55 @@
+# `tx_info`
+
+Cheatcodes modifying `tx_info`:
+
+## `spoof`
+
+> `fn spoof(target: CheatTarget, tx_info_mock: TxInfoMock, span: CheatSpan)`
+
+Changes `TxInfo` returned by `get_tx_info()` for the targeted contract and span.
+
+## `start_spoof`
+
+> `fn start_spoof(target: CheatTarget, tx_info_mock: TxInfoMock)`
+
+Changes `TxInfo` returned by `get_tx_info()` for the targeted contract until the spoof is canceled with `stop_spoof`.
+
+## `stop_spoof`
+
+> `fn stop_spoof(target: CheatTarget)`
+
+Cancels the `spoof` / `start_spoof` for the given target.
+
+
+## `TxInfoMock` & `TxInfoMockTrait`
+
+A structure used for setting individual fields in `TxInfo`
+All fields are optional, with optional value meaning as defined:
+- `None` means that the field is going to be reset to the initial value
+- `Some(n)` means that the value will be set to the `n` value
+```
+struct TxInfoMock {
+ version: Option<felt252>,
+ account_contract_address: Option<ContractAddress>,
+ max_fee: Option<u128>,
+ signature: Option<Span<felt252>>,
+ transaction_hash: Option<felt252>,
+ chain_id: Option<felt252>,
+ nonce: Option<felt252>,
+ // starknet::info::v2::TxInfo fields
+ resource_bounds: Option<Span<ResourceBounds>>,
+ tip: Option<u128>,
+ paymaster_data: Option<Span<felt252>>,
+ nonce_data_availability_mode: Option<u32>,
+ fee_data_availability_mode: Option<u32>,
+ account_deployment_data: Option<Span<felt252>>,
+}
+```
+
+Returns a default object initialized with Option::None for each field
+Useful for setting only a few of fields instead of all of them
+```
+trait TxInfoMockTrait {
+ fn default() -> TxInfoMock;
+}
+```
diff --git a/docs/src/appendix/cheatcodes/tx_info/README.md b/docs/src/appendix/cheatcodes/tx_info/README.md
diff --git a/docs/src/appendix/cheatcodes/tx_info/spoof.md b/docs/src/appendix/cheatcodes/tx_info/spoof.md
diff --git a/docs/src/appendix/cheatcodes/tx_info/start_spoof.md b/docs/src/appendix/cheatcodes/tx_info/start_spoof.md
diff --git a/docs/src/appendix/cheatcodes/tx_info/stop_spoof.md b/docs/src/appendix/cheatcodes/tx_info/stop_spoof.md
diff --git a/snforge_std/src/cheatcodes/tx_info.cairo b/snforge_std/src/cheatcodes/tx_info.cairo
@@ -3,6 +3,11 @@ use starknet::info::v2::ResourceBounds;
 use snforge_std::cheatcodes::{CheatSpan, CheatTarget, validate_cheat_target_and_span};
 use super::super::_cheatcode::handle_cheatcode;
 
+
+/// A structure used for setting individual fields in `TxInfo`
+/// All fields are optional, with optional value meaning as defined:
+/// - `None` means that the field is going to be reset to the initial value
+/// - `Some(value)` means that the field will be set to `value`
 #[derive(Copy, Drop, Serde)]
 struct TxInfoMock {
  version: Option<felt252>,
@@ -22,6 +27,8 @@ struct TxInfoMock {
 }
 
 trait TxInfoMockTrait {
+ /// Returns a default object initialized with Option::None for each field
+ /// Useful for setting only a few of fields instead of all of them
  fn default() -> TxInfoMock;
 }
 
@@ -45,6 +52,10 @@ impl TxInfoMockImpl of TxInfoMockTrait {
  }
 }
 
+/// Changes `TxInfo` returned by `get_tx_info()` for the targeted contract and span.
+/// - `target` - instance of `CheatTarget` specifying which contracts to spoof
+/// - `tx_info_mock` - a struct with same structure as `TxInfo` (returned by `get_tx_info()`)
+/// - `span` - instance of `CheatSpan` specifying the number of target calls with the cheat applied
 fn spoof(target: CheatTarget, tx_info_mock: TxInfoMock, span: CheatSpan) {
  validate_cheat_target_and_span(@target, @span);
 
@@ -55,10 +66,15 @@ fn spoof(target: CheatTarget, tx_info_mock: TxInfoMock, span: CheatSpan) {
  handle_cheatcode(cheatcode::<'spoof'>(inputs.span()));
 }
 
+/// Changes `TxInfo` returned by `get_tx_info()` for the targeted contract until the spoof is canceled with `stop_spoof`.
+/// - `target` - instance of `CheatTarget` specifying which contracts to spoof
+/// - `tx_info_mock` - a struct with same structure as `TxInfo` (returned by `get_tx_info()`)
 fn start_spoof(target: CheatTarget, tx_info_mock: TxInfoMock) {
  spoof(target, tx_info_mock, CheatSpan::Indefinite);
 }
 
+/// Cancels the `spoof` / `start_spoof` for the given target.
+/// - `target` - instance of `CheatTarget` specifying which contracts to stop spoofing
 fn stop_spoof(target: CheatTarget) {
  let mut inputs = array![];
  target.serialize(ref inputs);