Skip to content

Commit 2db6c85

Browse files
dkijaniadkijania
authored
Docs update for all components (#278)
* incorporate all voting dates from vitss into vitup * Revert "Auxiliary commit to revert individual files from 907300b" This reverts commit adf82300cffa3013ff3c6315600692cf42dd5d12. * Update vitup with newest changes from vit-servicing-station regarding multiple funds * prepare config structure for vitup. Split data section into current fund with more parameters and next funds with limited ones only for dates * point vitss dependency to master branch * expose flag for settings https protocol for quick start command. Disabling https in tests * iapyx docs * registation service docs * snapshot & registration verify service * valgrind docs * Revert "prepare config structure for vitup. Split data section into current fund with more parameters and next funds with limited ones only for dates" This reverts commit be0dcfc.
1 parent ae450d7 commit 2db6c85

File tree

33 files changed

+1029
-97
lines changed

33 files changed

+1029
-97
lines changed

‎.github/workflows/docs.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ jobs:
4141
run: mdbook build
4242

4343
- name: Deploy
44-
if: ${{ github.ref == 'refs/heads/master' }}
44+
if: ${{ github.ref == 'refs/heads/main' }}
4545
uses: peaceiris/actions-gh-pages@v3
4646
with:
4747
github_token: ${{ secrets.GITHUB_TOKEN }}

‎doc/SUMMARY.md

+10
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,16 @@
22

33
[Introduction](./introduction.md)
44

5+
- [Iapyx](./iapyx/iapyx.md)
6+
- [Load Tool](./iapyx/load.md)
7+
- [Registration Service](./registration-service/introduction.md)
8+
- [CLI](./registration-service/cli.md)
9+
- [Configuration](./registration-service/configuration.md)
10+
- [Snapshot Service](./snapshot-service/introduction.md)
11+
- [CLI](./snapshot-service/cli.md)
12+
- [Configuration](./snapshot-service/configuration.md)
13+
- [Valgrind](./valgrind/introduction.md)
14+
- [Configuration](./valgrind/configuration.md)
515
- [Vitup](./vitup/introduction.md)
616
- [Configuration](./vitup/configuration.md)
717
- [Data Generation](./vitup/data_generation.md)

‎doc/iapyx/iapyx.md

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Iapyx
2+
3+
Iapyx is a wallet cli & wallet api project which operates on catalyst-jormungandr network.
4+
5+
WARNING: main purpose of the wallet is testing. Do NOT use it on production.
6+
7+
## Build & Install
8+
9+
In order to build iapyx in main project folder run:
10+
```
11+
cd iapyx
12+
cargo build
13+
cargo install --path . --force
14+
```
15+
16+
## Quick Start
17+
18+
### CLI
19+
20+
Iapyx can be used as a wallet cli. It is capable of sending votes or pull data from node. The simplest usage example is available by using commands:
21+
22+
23+
* register new wallet based on qr code:
24+
`iapyx wallets import qr qr_file.png --pin 1234`
25+
26+
* connect to node rest API:
27+
`iapyx connect https://catalyst-backend.io/api`
28+
29+
* use recently created wallet for rest of commands:
30+
`iapyx wallets use darek`
31+
32+
* sync with the node and get wallet data:
33+
`iapyx wallets refresh`
34+
35+
* send vote:
36+
`iapyx vote single --choice yes --pin --id {proposal_id}`
37+
38+
### API
39+
40+
Iapyx can be used as api in order to perform voting operations from the code:
41+
42+
```
43+
44+
let wallet_proxy = spawn_network(...);
45+
let secret_file_path = Path::new("wallet_alice");
46+
47+
48+
let mut alice = iapyx::ControllerBuilder::default()
49+
.with_backend_from_client(wallet_proxy.client())?
50+
.with_wallet_from_secret_file(secret_file_path.as_ref())?
51+
.build()
52+
53+
let proposals = alice.proposals().unwrap();
54+
let votes_data = proposals
55+
.iter()
56+
.take(batch_size)
57+
.map(|proposal| (proposal, Choice::new(0)))
58+
.collect();
59+
60+
let fragment_ids = alice
61+
.votes_batch(votes_data)
62+
.unwrap()
63+
.iter()
64+
.map(|item| item.to_string())
65+
.collect();
66+
```
67+
68+
## Configuration
69+
70+
Iapyx api doesn't use any configuration files. However cli uses small cache folder on filesystem (located in: `~/.iapyx`).
71+
The purpose of this configuration is to store wallet lists as well as secret keys guarded by pass phrase.
72+
73+
### full list of available commands
74+
75+
Full list of commands is available on `iapyx --help` command.
76+
77+
```
78+
iapyx 0.0.1
79+
Command line wallet for testing Catalyst
80+
81+
USAGE:
82+
iapyx.exe <SUBCOMMAND>
83+
84+
FLAGS:
85+
-h, --help Prints help information
86+
-V, --version Prints version information
87+
88+
SUBCOMMANDS:
89+
address Gets address of wallet in bech32 format
90+
clear-tx Clears pending transactions to confirm. In case if expiration occurred
91+
confirm-tx Confirms successful transaction
92+
connect Sets node rest API address. Verifies connection on set
93+
funds Prints information about voting funds
94+
help Prints this message or the help of the given subcommand(s)
95+
logs Prints entire fragment logs from the node
96+
pending-transactions Prints pending transactions (not confirmed)
97+
proposals Prints proposals available to vote on
98+
refresh Pulls wallet data from the catalyst backend
99+
status Prints wallet status (balance/spending counters/tokens)
100+
statuses Prints pending or already sent fragments statuses
101+
vote Sends votes to backend
102+
votes Prints history of votes
103+
wallets Allows to manage wallets: add/remove/select operations
104+
```

‎doc/iapyx/load.md

+139
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Iapyx Load
2+
3+
Iapyx-load is a load cli & api project which operates on catalyst backend.
4+
5+
## Build & Install
6+
7+
In order to build iapyx-load in main project folder run:
8+
```
9+
cd testing/iapyx
10+
cargo build
11+
cargo install --path . --force
12+
```
13+
14+
## Quick Start
15+
16+
### CLI
17+
18+
Iapyx-load can be used as a cli. It is capable of putting various load on catalyst backend.
19+
Available load types:
20+
21+
* node-only - Load which targets blockchain calls only
22+
* static-only - Load which targets static data only
23+
* simulation - Load with simulate real user case (both blockchain and static data in some relation)
24+
25+
Also `node-only` load provides two load characteristic:
26+
* bursts - Bursts mode. Sends votes in batches and then wait x seconds
27+
* const - Constant load. Sends votes with x votes per second speed
28+
29+
And two scenario types:
30+
* duration - Duration based load. Defines how much time load should run
31+
* count - Requests count based load. Defines how many requests load should sent in total
32+
33+
Simplest load configuration is to use node-only load with below parameters:
34+
35+
`iapyx-load node-only const count --help`
36+
37+
```
38+
USAGE:
39+
iapyx-load.exe node-only const count [FLAGS] [OPTIONS] --requests-per-thread <count>
40+
41+
FLAGS:
42+
--debug Print additional information
43+
--help Prints help information
44+
--read-from-filename Read pin from filename of each qr code
45+
--reuse-accounts-early Update all accounts state before sending any vote
46+
--reuse-accounts-lazy Update account state just before sending vote
47+
-h, --https Use https for sending fragments
48+
-V, --version Prints version information
49+
50+
OPTIONS:
51+
-a, --address <address> Address in format: 127.0.0.1:8000 [default: 127.0.0.1:8000]
52+
-n, --requests-per-thread <count> How many requests per thread should be sent
53+
-c, --criterion <criterion> Pass criteria
54+
-d, --delay <delay> Amount of delay [miliseconds] between requests [default: 10000]
55+
--global-pin <global-pin> Global pin for all qr codes [default: 1234]
56+
-b, --progress-bar-mode <progress-bar-mode>
57+
Show progress. Available are (Monitor,Standard,None) [default: Monitor]
58+
59+
-q, --qr-codes-folder <qr-codes-folder> Qr codes source folder
60+
-s, --secrets-folder <secrets-folder> Secrets source folder
61+
--status-pace <status-pace> How frequent (in seconds) to print status [default: 1]
62+
-t, --threads <threads> Prints nodes related data, like stats,fragments etc [default: 3]
63+
```
64+
65+
### API
66+
67+
Iapyx load main purpose is to serve as load api:
68+
69+
```
70+
use iapyx::{NodeLoad, NodeLoadConfig};
71+
use jortestkit::{
72+
load::{ConfigurationBuilder, Monitor},
73+
measurement::Status,
74+
};
75+
76+
...
77+
78+
let no_of_threads = 10;
79+
let no_of_wallets = 40_000;
80+
81+
let mut qr_codes_folder = Path::new("qr-codes");
82+
83+
let config = ConfigurationBuilder::duration(parameters.calculate_vote_duration())
84+
.thread_no(threads_no)
85+
.step_delay(Duration::from_millis(delay))
86+
.fetch_limit(250)
87+
.monitor(Monitor::Progress(100))
88+
.shutdown_grace_period(Duration::from_secs(60))
89+
.build();
90+
91+
let load_config = NodeLoadConfig {
92+
batch_size,
93+
use_v1: false,
94+
config,
95+
criterion: Some(100),
96+
address: "127.0.0.1:8080".to_string(),
97+
qr_codes_folder: Some(qr_codes_folder),
98+
secrets_folder: None,
99+
global_pin: "".to_string(),
100+
reuse_accounts_lazy: false,
101+
reuse_accounts_early: false,
102+
read_pin_from_filename: true,
103+
use_https: false,
104+
debug: false,
105+
};
106+
107+
let iapyx_load = NodeLoad::new(load_config);
108+
if let Some(benchmark) = iapyx_load.start().unwrap() {
109+
assert!(benchmark.status() == Status::Green, "too low efficiency");
110+
}
111+
112+
```
113+
114+
### full list of available commands
115+
116+
Full list of commands is available on `mjolnir --help` command.
117+
118+
```
119+
mjolnir 0.1.0
120+
Jormungandr Load CLI toolkit
121+
122+
USAGE:
123+
mjolnir.exe [FLAGS] [SUBCOMMAND]
124+
125+
FLAGS:
126+
--full-version display full version details (software version, source version, targets and compiler used)
127+
-h, --help Prints help information
128+
--source-version display the sources version, allowing to check the source's hash used to compile this
129+
executable. this option is useful for scripting retrieving the logs of the version of this
130+
application
131+
-V, --version Prints version information
132+
133+
SUBCOMMANDS:
134+
explorer Explorer load
135+
fragment Fragment load
136+
help Prints this message or the help of the given subcommand(s)
137+
passive Passive Nodes bootstrap
138+
rest Rest load
139+
```

‎doc/integration-tests/introduction.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# integration-tests
2+
3+
Integration test is a container project for all catalyst e2e and integration tests. Tests are validating network correctness, stability. Also there are non-functional tests which verify node durability and reliability
4+
5+
## Architecture of tests
6+
7+
Integration tests architecture relies on test pyramid approach, where most of the effort is put into component and integration level and finally small amount of tests on E2E. Thanks to that we can create fast and reliable tests.
8+
9+
![Testing architecture](./graphs/testing-architecture.svg)
10+
11+
Before approaching Jormungandr testing we need to first remind ourselves a simplified architecture diagram for jcli & jormungandr.
12+
13+
![Simplified architecture](./graphs/catalyst-simplified-arch.svg)
14+
15+
## Quick start
16+
17+
### Prerequisites
18+
19+
In order to run test integration tests below components need to be installed or prebuild:
20+
- [vit-servicing-station-server|https://github.com/input-output-hk/vit-servicing-station/tree/master/vit-servicing-station-server]
21+
- [jormungandr|https://github.com/input-output-hk/jormungandr/tree/master/jormungandr]
22+
- [valgrind|https://github.com/input-output-hk/vit-testing/tree/master/valgrdin]
23+
24+
### Start tests
25+
26+
In order to build jormungandr-automation in main project folder run:
27+
```
28+
cd testing
29+
cargo test
30+
```
31+
32+
## Tests categories
33+
34+
Test are categories based on application/layer and property under test (functional or non-functional: load, perf etc.)
35+
Below diagram is a good overview:
36+
37+
![Test categories](./graphs/jormungandr-test-categories.svg)
38+
39+
### How to run all functional tests
40+
41+
```
42+
cd integration-tests
43+
cargo test
44+
```
45+
46+
### How to run testnet functional tests
47+
```
48+
cd integration-tests
49+
cargo test --features testnet-tests
50+
```
51+
52+
### How to run load tests
53+
```
54+
cd integration-tests
55+
cargo test non_functional::load --features load-tests
56+
```
57+
58+
### How to run network endurance tests
59+
```
60+
cd testing/jormungandr-integration-tests
61+
cargo test non_functional::soak --features soak-tests
62+
```
63+
64+
### Frequency
65+
Functional tests are run on each PR. Performance and testnet integration tests are run nightly

‎doc/registration-service/cli.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Registration CLI
2+
3+
Registration CLI is cli utility tool which help to interact with registration service.
4+
5+
6+
## Build & Install
7+
8+
In order to build iapyx in main project folder run:
9+
```
10+
cd registration-service
11+
cargo build
12+
cargo install --path . --force
13+
```
14+
15+
## Quick Start
16+
17+
The simplest usage example is available by using commands:
18+
19+
* register new job:
20+
`registration-cli job new --payment-skey payment.skey --payment-vkey payment.vkey --stake-skey stake.skey --stake-vkey stake.vkey --endpoint https://{ADDRESS}`
21+
22+
NOTE: response of the above call should return `job-id` which should be used in next call
23+
24+
NOTE: see [cardano cli guide](https://developers.cardano.org/docs/stake-pool-course/handbook/keys-addresses/) for information how to create payment and stake files.
25+
26+
* check job id:
27+
`registration-cli job status --job-id {job-id} --endpoint https://{ADDRESS}`
28+
29+
### full list of available commands
30+
31+
Full list of commands is available on `registration-cli --help` command.
32+
33+
```
34+
registration-service 0.1.0
35+
36+
USAGE:
37+
registration-cli.exe [OPTIONS] --endpoint <endpoint> <SUBCOMMAND>
38+
39+
FLAGS:
40+
-h, --help Prints help information
41+
-V, --version Prints version information
42+
43+
OPTIONS:
44+
-e, --endpoint <endpoint> registration service endpoint [env: REGISTRATION_ENDPOINT=]
45+
-t, --token <token> access token [env: REGISTRATION_TOKEN=]
46+
47+
SUBCOMMANDS:
48+
files download jobs artifacts
49+
health check if registration service is up
50+
help Prints this message or the help of the given subcommand(s)
51+
job jobs related operations
52+
```

0 commit comments

Comments
 (0)