Skip to content

Commit 8301912

Browse files
azixusCluEleSsUK
azixus
and
CluEleSsUK
authored
fix blocklock/randomness configurations & docs (#260)
* fix(config): remove serde's auto TryFrom `CommitteeConfigFiles` for `CommitteeConfig` * docs(randomness): add instructions in README.md * docs(blocklock): add instructions in README.md * docs(randomness|blocklock): add new sync arguments to docs * Update bin/blocklock-agent/README.md Co-authored-by: PM <3749956+CluEleSsUK@users.noreply.github.com> --------- Co-authored-by: PM <3749956+CluEleSsUK@users.noreply.github.com>
1 parent 4f2f061 commit 8301912

3 files changed

Lines changed: 268 additions & 2 deletions

File tree

‎bin/blocklock-agent/README.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Blocklock Agent
2+
3+
A decentralized blocklock agent that fulfills on-chain blocklock requests through the [`blocklock-solidity`](https://github.com/randa-mu/blocklock-solidity) contracts.
4+
5+
## Prerequisites
6+
- Deployed [`blocklock-solidity`](https://github.com/randa-mu/blocklock-solidity) contracts,
7+
- A committee configuration file, issued from a key generation ceremony.
8+
9+
## Configuration
10+
11+
The agent can be configured via command-line arguments, environment variables, or a TOML configuration file.
12+
13+
## Committee Configuration File
14+
15+
Create a `committee.toml` file with your committee settings:
16+
17+
```toml
18+
# Your member ID within the committee
19+
member_id = 1
20+
21+
# Your secret signing key (base64 encoded)
22+
secret_key = "HBIjfH5BaOBP9yJKDiNaTSwYxPHNaz06wgHI58j1bOg="
23+
24+
# Total number of committee members
25+
n = 4
26+
27+
# Minimum signatures required (threshold)
28+
signing_threshold = 2
29+
30+
# Committee member details
31+
[[members]]
32+
member_id = 1
33+
bls_pk = "5Bfq2cbTCQMB9iCB6zVU/BY0YShDCxtF4Imede78hFELCp8unobkd6XLf+Pno5dqJOVyEidv3XTKa53ubfcO2Q==" # compressed, base64 encoded
34+
peer_id = "12D3KooWMSH17hbmMBSbEtCeyYBkFT7phd6PVaA2fdxakaTAuXMx"
35+
address = "/ip4/127.0.0.1/tcp/15001"
36+
37+
[[members]]
38+
member_id = 2
39+
bls_pk = "qD1qMeZa/7dJ4ZoymmozhtYnTFn96KyqfWMunyGgfecgqHUDeAKXhul4UMiQTVRfl2CSUKpFulwUean1mVgIKg=="
40+
peer_id = "12D3KooWMAADWEWNMFCNBadQfNFLeHHcYeZr9tNJBekY4opdCzDM"
41+
address = "/ip4/127.0.0.1/tcp/15002"
42+
43+
[[members]]
44+
member_id = 3
45+
bls_pk = "lmnhNX86rLuqxNh+JxTX/GQnZPoP91g0ye8JB8dZAD4gKY00BgxhWtwdefMkShfWV7CNllRBJItcfemL0HBa/w=="
46+
peer_id = "12D3KooWHpwkbFiQ9af1jm3JxH2gGj5s5dWjuzaTLkEvKXikvL1U"
47+
address = "/ip4/127.0.0.1/tcp/15003"
48+
49+
[[members]]
50+
member_id = 4
51+
bls_pk = "pLNDWGmc1HflnVbJAzYVt/0Wymh8mGojIVeWXP53KvAM3uoUa8X4XTR0h7otlmlNoxqryKRTAAcl7aCtpV7dVg=="
52+
peer_id = "12D3KooWFka9jyk6N9VtM36gsUgJPcmjw4NANxWgbx66VNgRAPcj"
53+
address = "/ip4/127.0.0.1/tcp/15004"
54+
```
55+
56+
### Creating the Committee File from ADKG Output
57+
58+
To create this file from the output of the ADKG tool in this repository, one must proceed as follows:
59+
1. Take the public output of the ADKG, specifically `node_pks`, and fill the members list by renaming the various fields,
60+
2. set the secret key from the ADKG's private output,
61+
3. set `n` to the number of parties in the group file, and,
62+
4. set `signing_threshold` to `t_reconstruction + 1` which is specified in the group file.
63+
64+
## Running the Agent
65+
66+
### Minimal Example
67+
68+
```bash
69+
cargo run --example blocklock -- \
70+
--committee-config ./committee.toml \
71+
--rpc-url wss://wss.calibration.node.glif.io/apigw/lotus/rpc/v1 \
72+
--tx-private-key YOUR_TX_PRIVATE_KEY \
73+
--libp2p-key YOUR_LIBP2P_PRIVATE_KEY \
74+
--blocklock-sender-addr 0x1234567890123456789012345678901234567890 \
75+
--decryption-sender-addr 0x0987654321098765432109876543210987654321
76+
```
77+
78+
## Configuration Options
79+
80+
### Required Arguments
81+
82+
| Argument | Environment Variable | Description |
83+
|----------------------------|------------------------------------------------|--------------------------------------------|
84+
| `--committee-config` | `BLOCKLOCK_COMMITTEE_CONFIG` | Path to committee configuration TOML file |
85+
| `--rpc-url` | `BLOCKLOCK_RPC_URL` | Blockchain WebSocket RPC URL |
86+
| `--tx-private-key` | `BLOCKLOCK_TX_PRIVATE_KEY` | Private key for transaction signing |
87+
| `--libp2p-key` | `BLOCKLOCK_LIBP2P_KEY` | Libp2p private key |
88+
| `--blocklock-sender-addr` | `BLOCKLOCK_SENDER_CONTRACT_ADDRESS` | Deployed BlocklockSender contract address |
89+
| `--decryption-sender-addr` | `BLOCKLOCK_DECRYPTION_SENDER_CONTRACT_ADDRESS` | Deployed DecryptionSender contract address |
90+
91+
### Health Check
92+
93+
| Argument | Environment Variable | Default | Description |
94+
|-----------------------------|-------------------------------------|-----------|----------------------------------|
95+
| `--healthcheck-listen-addr` | `BLOCKLOCK_HEALTHCHECK_LISTEN_ADDR` | `0.0.0.0` | Health check server bind address |
96+
| `--healthcheck-port` | `BLOCKLOCK_HEALTHCHECK_PORT` | `8080` | Health check server port |
97+
98+
### Blockchain Configuration
99+
100+
| Argument | Environment Variable | Default | Description |
101+
|---------------------------------|-------------------------------------|-------------|------------------------------------------------------------------------|
102+
| `--chain-id` | `BLOCKLOCK_CHAIN_ID` | Auto-detect | Blockchain chain ID |
103+
| `--tx-fulfillment-disabled` | `BLOCKLOCK_TX_FULFILLMENT_DISABLED` | `false` | Disable transaction fulfillment |
104+
| `--min-confirmations` | `BLOCKLOCK_MIN_CONFIRMATIONS` | `1` | Required block confirmations |
105+
| `--confirmations-timeout-secs` | `BLOCKLOCK_CONFIRMATIONS_TIMEOUT` | `60` | Confirmation timeout (seconds) |
106+
| `--max-tx-per-tick` | `BLOCKLOCK_MAX_TX_PER_TICK` | unlimited | Max transactions per tick |
107+
| `--tx-retry-strategy` | `BLOCKLOCK_TX_RETRY_STRATEGY` | `Never` | Retry strategy |
108+
| `--sync-batch-size` | `BLOCKLOCK_SYNC_BATCH_SIZE` | `20` | Blockchain sync batch size |
109+
| `--contract-sync-interval-secs` | `BLOCKLOCK_CONTRACT_SYNC_INTERVAL` | `30` | How often to sync the current state / block height against the chain. |
110+
| `--fulfillment-interval-secs` | `BLOCKLOCK_FULFILLMENT_INTERVAL` | `60` | How often to retry sending transactions / fulfilling pending requests. |
111+
112+
### Gas & Profitability
113+
114+
| Argument | Environment Variable | Default | Description |
115+
|------------------------------|--------------------------------------|---------|-----------------------------|
116+
| `--gas-price-buffer-percent` | `BLOCKLOCK_GAS_PRICE_BUFFER_PERCENT` | `20` | Gas price bump percentage |
117+
| `--gas-buffer-percent` | `BLOCKLOCK_GAS_BUFFER_PERCENT` | `20` | Gas limit buffer percentage |
118+
| `--profit-threshold` | `BLOCKLOCK_PROFIT_THRESHOLD_PERCENT` | `20` | Minimum profit threshold |
119+
120+
### Libp2p Networking
121+
122+
| Argument | Environment Variable | Default | Description |
123+
|------------------------|--------------------------------|-------------------------|----------------------------|
124+
| `--libp2p-listen-addr` | `BLOCKLOCK_LIBP2P_LISTEN_ADDR` | `/ip4/0.0.0.0/tcp/9001` | Libp2p listen multiaddress |
125+
126+
### State & Logging
127+
128+
| Argument | Environment Variable | Default | Description |
129+
|----------------|----------------------------------|--------------------------|--------------------------------|
130+
| `--state-file` | `BLOCKLOCK_SAVED_STATE_FILENAME` | `./blocklock_state.json` | Persistent agent state file |
131+
| `--log-level` | `BLOCKLOCK_LOG_LEVEL` | `info` | Log verbosity |
132+
| `--log-json` | `BLOCKLOCK_LOG_JSON` | `false` | Enable structured JSON logging |

‎bin/randomness-agent/README.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
2+
# Randomness Agent
3+
4+
A decentralized randomness agent that fulfills randomness requests on blockchain networks through the [`randomness-solidity`](https://github.com/randa-mu/randomness-solidity) contracts.
5+
6+
## Prerequisites
7+
- Deployed [`randomness-solidity`](https://github.com/randa-mu/randomness-solidity) contracts,
8+
- A committee configuration file, issued from a key generation ceremony.
9+
10+
## Configuration
11+
12+
The agent can be configured via command-line arguments, environment variables, or a TOML configuration file.
13+
14+
### Committee Configuration File
15+
16+
Create a `committee.toml` file with your committee settings:
17+
18+
```toml
19+
# Your member ID within the committee
20+
member_id = 1
21+
22+
# Your secret signing key (base64 encoded)
23+
secret_key = "HBIjfH5BaOBP9yJKDiNaTSwYxPHNaz06wgHI58j1bOg="
24+
25+
# Total number of committee members
26+
n = 4
27+
28+
# Minimum signatures required (threshold)
29+
signing_threshold = 2
30+
31+
# Committee member details
32+
[[members]]
33+
member_id = 1
34+
bls_pk = "5Bfq2cbTCQMB9iCB6zVU/BY0YShDCxtF4Imede78hFELCp8unobkd6XLf+Pno5dqJOVyEidv3XTKa53ubfcO2Q==" # compressed, base64 encoded
35+
peer_id = "12D3KooWMSH17hbmMBSbEtCeyYBkFT7phd6PVaA2fdxakaTAuXMx"
36+
address = "/ip4/127.0.0.1/tcp/15001"
37+
38+
[[members]]
39+
member_id = 2
40+
bls_pk = "qD1qMeZa/7dJ4ZoymmozhtYnTFn96KyqfWMunyGgfecgqHUDeAKXhul4UMiQTVRfl2CSUKpFulwUean1mVgIKg=="
41+
peer_id = "12D3KooWMAADWEWNMFCNBadQfNFLeHHcYeZr9tNJBekY4opdCzDM"
42+
address = "/ip4/127.0.0.1/tcp/15002"
43+
44+
[[members]]
45+
member_id = 3
46+
bls_pk = "lmnhNX86rLuqxNh+JxTX/GQnZPoP91g0ye8JB8dZAD4gKY00BgxhWtwdefMkShfWV7CNllRBJItcfemL0HBa/w=="
47+
peer_id = "12D3KooWHpwkbFiQ9af1jm3JxH2gGj5s5dWjuzaTLkEvKXikvL1U"
48+
address = "/ip4/127.0.0.1/tcp/15003"
49+
50+
[[members]]
51+
member_id = 4
52+
bls_pk = "pLNDWGmc1HflnVbJAzYVt/0Wymh8mGojIVeWXP53KvAM3uoUa8X4XTR0h7otlmlNoxqryKRTAAcl7aCtpV7dVg=="
53+
peer_id = "12D3KooWFka9jyk6N9VtM36gsUgJPcmjw4NANxWgbx66VNgRAPcj"
54+
address = "/ip4/127.0.0.1/tcp/15004"
55+
```
56+
57+
To create this file from the output of the ADKG tool in this repository, one must proceed as follows:
58+
1. Take the public output of the ADKG, specifically `node_pks`, and fill the members list by renaming the various fields,
59+
2. set the secret key from the ADKG's private output,
60+
3. set `n` to the number of parties in the group file, and,
61+
4. set `signing_threshold` to `t_reconstruction + 1` which is specified in the group file.
62+
63+
## Running the Agent
64+
65+
### Minimal Example
66+
67+
```bash
68+
cargo run --example randomness -- \
69+
--committee-config ./committee.toml \
70+
--rpc-url wss://eth.drpc.org \
71+
--tx-private-key YOUR_PRIVATE_KEY \
72+
--libp2p-key YOUR_LIBP2P_PRIVATE_KEY \
73+
--signature-sender-addr 0x1234567890123456789012345678901234567890 \
74+
--randomness-sender-addr 0x0987654321098765432109876543210987654321
75+
```
76+
77+
Note that parameters may also be set through environment variables, see the table below.
78+
79+
## Configuration Options
80+
81+
### Required Arguments
82+
83+
| Argument | Environment Variable | Description |
84+
|----------------------------|------------------------------------------------|---------------------------------------------------|
85+
| `--committee-config` | `RANDOMNESS_COMMITTEE_CONFIG` | Path to committee configuration TOML file |
86+
| `--rpc-url` | `RANDOMNESS_RPC_URL` | Blockchain websockets RPC URL |
87+
| `--tx-private-key` | `RANDOMNESS_TX_PRIVATE_KEY` | Private key for signing transactions (hex format) |
88+
| `--libp2p-key` | `RANDOMNESS_LIBP2P_KEY` | Private key for libp2p networking |
89+
| `--signature-sender-addr` | `RANDOMNESS_SIGNATURE_SENDER_CONTRACT_ADDRESS` | Address of deployed SignatureSender contract |
90+
| `--randomness-sender-addr` | `RANDOMNESS_SENDER_CONTRACT_ADDRESS` | Address of deployed RandomnessSender contract |
91+
92+
### Optional Arguments
93+
94+
#### Health Check
95+
96+
| Argument | Environment Variable | Default | Description |
97+
|-----------------------------|--------------------------------------|-----------|------------------------------------|
98+
| `--healthcheck-listen-addr` | `RANDOMNESS_HEALTHCHECK_LISTEN_ADDR` | `0.0.0.0` | IP address for health check server |
99+
| `--healthcheck-port` | `RANDOMNESS_HEALTHCHECK_PORT` | `8080` | Port for health check server |
100+
101+
#### Blockchain Configuration
102+
103+
| Argument | Environment Variable | Default | Description |
104+
|---------------------------------|--------------------------------------|-------------|------------------------------------------------------------------------|
105+
| `--chain-id` | `RANDOMNESS_CHAIN_ID` | Auto-detect | Blockchain network chain ID |
106+
| `--tx-fulfillment-disabled` | `RANDOMNESS_TX_FULFILLMENT_DISABLED` | `false` | Disable transaction fulfillment (monitoring only) |
107+
| `--min-confirmations` | `RANDOMNESS_MIN_CONFIRMATIONS` | `1` | Block confirmations required |
108+
| `--confirmations-timeout-secs` | `RANDOMNESS_CONFIRMATIONS_TIMEOUT` | `60` | Timeout in seconds for confirmations |
109+
| `--max-tx-per-tick` | `RANDOMNESS_MAX_TX_PER_TICK` | unlimited | Maximum transactions per processing cycle |
110+
| `--tx-retry-strategy` | `RANDOMNESS_TX_RETRY_STRATEGY` | `Never` | Retry strategy for failed transactions |
111+
| `--sync-batch-size` | `RANDOMNESS_SYNC_BATCH_SIZE` | `20` | Batch size for blockchain sync |
112+
| `--sig-compression` | `RANDOMNESS_SIG_COMPRESSION` | `false` | Enable on-chain signature compression |
113+
| `--contract-sync-interval-secs` | `RANDOMNESS_CONTRACT_SYNC_INTERVAL` | `30` | How often to sync the current state against the chain. |
114+
| `--fulfillment-interval-secs` | `RANDOMNESS_FULFILLMENT_INTERVAL` | `60` | How often to retry sending transactions / fulfilling pending requests. |
115+
116+
#### Gas & Profitability
117+
118+
| Argument | Environment Variable | Default | Description |
119+
|------------------------------|---------------------------------------|---------|-------------------------------------|
120+
| `--gas-price-buffer-percent` | `RANDOMNESS_GAS_PRICE_BUFFER_PERCENT` | `20` | Gas price buffer percentage |
121+
| `--gas-buffer-percent` | `RANDOMNESS_GAS_BUFFER_PERCENT` | `20` | Gas limit buffer percentage |
122+
| `--profit-threshold` | `RANDOMNESS_PROFIT_THRESHOLD_PERCENT` | `20` | Minimum profit threshold percentage |
123+
124+
#### Libp2p Networking
125+
126+
| Argument | Environment Variable | Default | Description |
127+
|------------------------|---------------------------------|-------------------------|----------------------------|
128+
| `--libp2p-listen-addr` | `RANDOMNESS_LIBP2P_LISTEN_ADDR` | `/ip4/0.0.0.0/tcp/9001` | Libp2p listen multiaddress |
129+
130+
#### Logging
131+
132+
| Argument | Environment Variable | Default | Description |
133+
|---------------|------------------------|---------|---------------------------------------------|
134+
| `--log-level` | `RANDOMNESS_LOG_LEVEL` | `info` | Log level (trace, debug, info, warn, error) |
135+
| `--log-json` | `RANDOMNESS_LOG_JSON` | `false` | Output logs in JSON format |

‎crates/config/src/signing.rs‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,6 @@ use utils::serialize::point::PointDeserializeCompressed;
88
use utils::serialize::point::PointSerializeCompressed;
99

1010
#[derive(Serialize, Deserialize, Debug, Clone)]
11-
// Deserialize as a CommitteeConfigFiles first, and call try_from to get Self
12-
#[serde(try_from = "CommitteeConfigFiles")]
1311
#[serde(bound(
1412
serialize = "G: PointSerializeCompressed",
1513
deserialize = "G: PointDeserializeCompressed"
@@ -30,6 +28,7 @@ pub struct CommitteeConfig<G: AffineRepr> {
3028
// all the details we need to contact and verify messages from other nodes
3129
pub members: Vec<MemberConfig<G>>,
3230
}
31+
3332
#[derive(Serialize, Deserialize, Debug, Clone)]
3433
pub struct CommitteeConfigFiles {
3534
pub adkg_public: AdkgPublic,

0 commit comments

Comments
 (0)