Skip to content

Commit 11c2914

Browse files
ericpassmoreericpassmore
authored
Merge pull request #1854 from AntelopeIO/trx_generator_docs
[Main] How To Run `trx_generator`
2 parents 83d6d3d + 86ed139 commit 11c2914

File tree

1 file changed

+120
-53
lines changed

1 file changed

+120
-53
lines changed

‎tests/trx_generator/README.md‎

Lines changed: 120 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,132 @@
11
# Transaction Generator
22

3-
The Transaction Generator is a program built to create and send transactions at a specified rate in order to generate load on a blockchain. It is comprised of 3 main components: Transaction Generator, Transaction Provider, and Performance Monitor.
3+
The Transaction Generator is a program built to create and send transactions at a specified rate in order to generate load on a blockchain. It is comprised of 3 main components: Transaction Generator, Transaction Provider, and Performance Monitor.
44

5-
The `trx_generator.[hpp, cpp]` is currently specialized to be a `transfer_trx_generator` primarily focused on generating token transfer transactions. The transactions are then provided to the network by the `trx_provider.[hpp, cpp]` which is currently aimed at the P2P network protocol in the `p2p_trx_provider`. The third component, the `tps_performance_monitor`, allows the Transaction Generator to monitor its own performance and take action to notify and exit if it is unable to keep up with the requested transaction generation rate.
5+
The `trx_generator.[hpp, cpp]` is currently specialized to be a `transfer_trx_generator` primarily focused on generating token transfer transactions. The transactions are then provided to the network by the `trx_provider.[hpp, cpp]` which is currently aimed at the P2P network protocol in the `p2p_trx_provider`. The third component, the `tps_performance_monitor`, allows the Transaction Generator to monitor its own performance and take action to notify and exit if it is unable to keep up with the requested transaction generation rate.
66

7-
The Transaction Generator logs each transaction's id and sent timestamp at the moment the Transaction Provider sends the transaction. Logs are written to the configured log directory and will follow the naming convention `trx_data_output_10744.txt` where `10744` is the transaction generator instance's process ID.
7+
The Transaction Generator logs each transaction's id and sent timestamp at the moment the Transaction Provider sends the transaction. Logs are written to the configured log directory and will follow the naming convention `trx_data_output_10744.txt` where `10744` is the transaction generator instance's process ID.
88

99
## Configuration Options
10+
1011
`./build/tests/trx_generator/trx_generator` can be configured using the following command line arguments:
1112

1213
<details open>
1314
<summary>Expand Argument List</summary>
1415

15-
* `--generator-id arg` (=0) Id for the transaction generator.
16-
Allowed range (0-960). Defaults to 0.
17-
* `--chain-id arg` set the chain id
18-
* `--contract-owner-account arg` Account name of the contract account
19-
for the transaction actions
20-
* `--accounts arg` comma-separated list of accounts that
21-
will be used for transfers. Minimum
22-
required accounts: 2.
23-
* `--priv-keys arg` comma-separated list of private keys in
24-
same order of accounts list that will
25-
be used to sign transactions. Minimum
26-
required: 2.
27-
* `--trx-expiration arg` (=3600) transaction expiration time in seconds.
28-
Defaults to 3,600. Maximum allowed:
29-
3,600
30-
* `--trx-gen-duration arg` (=60) Transaction generation duration
31-
(seconds). Defaults to 60 seconds.
32-
* `--target-tps arg` (=1) Target transactions per second to
33-
generate/send. Defaults to 1
34-
transaction per second.
35-
* `--last-irreversible-block-id arg` Current last-irreversible-block-id (LIB
36-
ID) to use for transactions.
37-
* `--monitor-spinup-time-us arg` (=1000000)
38-
Number of microseconds to wait before
39-
monitoring TPS. Defaults to 1000000
40-
(1s).
41-
* `--monitor-max-lag-percent arg` (=5) Max percentage off from expected
42-
transactions sent before being in
43-
violation. Defaults to 5.
44-
* `--monitor-max-lag-duration-us arg` (=1000000)
45-
Max microseconds that transaction
46-
generation can be in violation before
47-
quitting. Defaults to 1000000 (1s).
48-
* `--log-dir arg` set the logs directory
49-
* `--stop-on-trx-failed arg` (=1) stop transaction generation if sending
50-
fails.
51-
* `--abi-file arg` The path to the contract abi file to
52-
use for the supplied transaction action
53-
data
54-
* `--actions-data arg` The json actions data file or json
55-
actions data description string to use
56-
* `--actions-auths arg` The json actions auth file or json
57-
actions auths description string to
58-
use, containting authAcctName to
59-
activePrivateKey pairs.
60-
* `--peer-endpoint arg` (=127.0.0.1) set the peer endpoint to send
61-
transactions to
62-
* `--port arg` (=9876) set the peer endpoint port to send
63-
transactions to
64-
* `-h [ --help ]` print this list
16+
- `--generator-id arg` (=0) Id for the transaction generator.
17+
Allowed range (0-960). Defaults to 0.
18+
- `--chain-id arg` set the chain id
19+
- `--contract-owner-account arg` Account name of the contract account
20+
for the transaction actions
21+
- `--accounts arg` comma-separated list of accounts that
22+
will be used for transfers. Minimum
23+
required accounts: 2.
24+
- `--priv-keys arg` comma-separated list of private keys in
25+
same order of accounts list that will
26+
be used to sign transactions. Minimum
27+
required: 2.
28+
- `--trx-expiration arg` (=3600) transaction expiration time in seconds.
29+
Defaults to 3,600. Maximum allowed:
30+
3,600
31+
- `--trx-gen-duration arg` (=60) Transaction generation duration
32+
(seconds). Defaults to 60 seconds.
33+
- `--target-tps arg` (=1) Target transactions per second to
34+
generate/send. Defaults to 1
35+
transaction per second.
36+
- `--last-irreversible-block-id arg` Current last-irreversible-block-id (LIB
37+
ID) to use for transactions.
38+
- `--monitor-spinup-time-us arg` (=1000000)
39+
Number of microseconds to wait before
40+
monitoring TPS. Defaults to 1000000
41+
(1s).
42+
- `--monitor-max-lag-percent arg` (=5) Max percentage off from expected
43+
transactions sent before being in
44+
violation. Defaults to 5.
45+
- `--monitor-max-lag-duration-us arg` (=1000000)
46+
Max microseconds that transaction
47+
generation can be in violation before
48+
quitting. Defaults to 1000000 (1s).
49+
- `--log-dir arg` set the logs directory
50+
- `--stop-on-trx-failed arg` (=1) stop transaction generation if sending
51+
fails.
52+
- `--abi-file arg` The path to the contract abi file to
53+
use for the supplied transaction action
54+
data
55+
- `--actions-data arg` The json actions data file or json
56+
actions data description string to use
57+
- `--actions-auths arg` The json actions auth file or json
58+
actions auths description string to
59+
use, containting authAcctName to
60+
activePrivateKey pairs.
61+
- `--peer-endpoint arg` (=127.0.0.1) set the peer endpoint to send
62+
transactions to
63+
- `--port arg` (=9876) set the peer endpoint port to send
64+
transactions to
65+
- `-h [ --help ]` print this list
6566
</details>
67+
68+
## Running Other Actions
69+
70+
Instructions and examples for running `trx_generator` to create transactions with the custom action instead of the default transfer actions. The tool uses the ABI to serialize the action and sign the transactions with the provided private keys. If you need to generate unique account names per transaction (e.g., for account creation actions), the tool supports placeholders like `ACCT_PER_TRX` in the action, which it will replace with generated names.
71+
72+
1. **Prepare the ABI File**: Specify the path to the ABI file, using the `--abi-file` option. This file describes the structure of the actions available in the contract.
73+
74+
Example: `--abi-file path/to/contract.abi`
75+
76+
2. **Define Action Data**: Use the `--actions-data` option to provide a JSON file or string that describes the action(s) you want to include in the transactions. This JSON should specify the action name, the account associated with the action, and the data payload for the action as per the ABI. The `actionAuthAcct` and `authorization:actor` specify the account that signs and executes the action, typically using the same account name, and do not reference the contract owner's account, which is specified separately via the `--contract-owner-account` option.
77+
78+
Example JSON structure for action data:
79+
80+
```json
81+
[
82+
{
83+
"actionName": "youraction",
84+
"actionAuthAcct": "accountname",
85+
"actionData": {
86+
"param1": "value1",
87+
"param2": "value2"
88+
},
89+
"authorization": {
90+
"actor": "accountname",
91+
"permission": "active"
92+
}
93+
}
94+
]
95+
```
96+
97+
This may be passed directly as a string or passed as path to a file with the same information:
98+
`--actions-data path/to/actions.json` or `--actions-data '[{"actionName": "youraction", ...}]'`
99+
100+
3. **Specify Authorization Keys**: Provide the private key needed to sign the transaction on on the user's behalf. This is done with the `--actions-auths` option. It's a JSON file that maps the account name to the corresponding private key. The `accountname` here must match the `authorization:actor@permission` specified in the `action-data` JSON.
101+
102+
Example JSON structure for auths:
103+
104+
```json
105+
{
106+
"accountname": "privatekeystring"
107+
}
108+
```
109+
110+
The JSON can include multiple account names mapped to their respective private keys if needed.
111+
112+
```json
113+
{
114+
"accountname1": "privatekeystring1",
115+
"accountname2": "privatekeystring2"
116+
}
117+
```
118+
119+
This may be passed as a string or file path:
120+
`--actions-auths path/to/auths.json` or `--actions-auths '{"accountname": "privatekeystring"}'`
121+
122+
4. **Set Contract Owner Account**: Ensure the `--contract-owner-account` option is set for the action specified in the `action-data` JSON.
123+
124+
Example: `--contract-owner-account contractaccount`
125+
126+
5. **Run the Generator**: Execute the `trx_generator` with these options along with other necessary configurations like `--chain-id`, `--last-irreversible-block-id`, `--target-tps`, etc., to generate and send transactions with your custom action.
127+
128+
Full command example:
129+
130+
```bash
131+
./build/tests/trx_generator/trx_generator --generator-id 1 --chain-id yourchainid --contract-owner-account contractaccount --abi-file path/to/contract.abi --actions-data path/to/actions.json --actions-auths path/to/auths.json --last-irreversible-block-id yourlibid --target-tps 10 --trx-gen-duration 60 --log-dir logs
132+
```

0 commit comments

Comments
 (0)