Skip to content

Commit a76eeaf

Browse files
tacyargtacyarg
committed
better docs
1 parent 99ad615 commit a76eeaf

File tree

4 files changed

+106
-138
lines changed

4 files changed

+106
-138
lines changed

‎README.md‎

Lines changed: 92 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ This is a random number generator core library that uses various hashing functio
1212
Import the generator function in your project:
1313

1414
```javascript
15-
const Provable = require("@provableio/provable-core");
15+
const { Provable, HashChain, HashSeries, utils } = require("@provableio/provable-core");
1616
```
1717

1818
Create an instance of the generator with your desired configuration:
@@ -37,6 +37,97 @@ The `config` object contains the following properties:
3737
- `nonce` (number): The current nonce value.
3838
- `cursor` (number): The current cursor value.
3939

40+
## Available methods
41+
42+
The Provable instance has the following methods:
43+
44+
### next(salt, clientSeed)
45+
46+
Returns an object containing the next `clientSeed` and `serverSeed` values based on the provided `salt` and `clientSeed` values. If `clientSeed` is not provided, it will be generated using the `md5` hashing function.
47+
48+
```javascript
49+
const nextValues = generator.next("salt-value");
50+
console.log(nextValues); // { clientSeed: "generated-client-seed", serverSeed: "generated-server-seed" }
51+
```
52+
53+
### state()
54+
55+
Returns the current configuration object.
56+
57+
```javascript
58+
const currentConfig = generator.state();
59+
console.log(currentConfig); // { clientSeed: "your-client-seed", serverSeed: "your-server-seed", nonce: 0, emit: [Function: emit] }
60+
```
61+
62+
### floats(count)
63+
64+
Generates `count` number of random floating-point numbers using the configured generator. The `count` argument is optional and defaults to `1`.
65+
66+
```javascript
67+
const randomFloats = generator.floats(5);
68+
console.log(randomFloats); // [0.123456789, 0.234567890, 0.345678901, 0.4567890123, 0.56789012345]
69+
```
70+
71+
The generator's configuration is updated after generating the random numbers, and the `nonce` value is incremented. If an `emit` callback function is provided, it will be called with the updated configuration.
72+
73+
### ints(count, max, min)
74+
75+
Generates `count` number of random integer numbers within the range of `min` and `max` (inclusive) using the configured generator. The `count`, `max`, and `min` arguments are optional and default to `1`, `100`, and `0`, respectively.
76+
77+
```javascript
78+
const randomInts = generator.ints(10, 50, -25);
79+
console.log(randomInts); // [-25, -24, -23, -22, -21, -20, -19, -18, -17, -16]
80+
```
81+
82+
The generator's configuration is updated after generating the random numbers, and the `nonce` value is incremented. If an `emit` callback function is provided, it will be called with the updated configuration.
83+
84+
### tick()
85+
86+
Increments the `nonce` value and emits the updated configuration (if an `emit` callback function is provided).
87+
88+
```javascript
89+
generator.tick();
90+
```
91+
92+
## Additional Generators
93+
94+
### HashSeries({ seed, salt, nonce })
95+
96+
This class is used to generate a series of hashes based on the provided `seed`, `salt`, and `nonce` values. It has the following methods:
97+
98+
- `getHash()`: Returns the current hash value.
99+
- `next()`: Increments the `nonce` value and returns a new object with the updated `seed`, `salt`, and `nonce`.
100+
- `peekHash()`: Returns the next hash value based on the updated `nonce` value.
101+
- `calcHash(_seed, _salt, _nonce)`: Calculates the hash value using the provided `seed`, `salt`, and `nonce` values.
102+
- `state()`: Returns an object containing the `seed`, `salt`, and `nonce` values.
103+
104+
```javascript
105+
const hashSeries = new HashSeries({ seed: "your-seed", salt: "your-salt", nonce: 0 });
106+
console.log(hashSeries.getHash()); // Generated hash value
107+
console.log(hashSeries.next()); // { seed: "your-seed", salt: "your-salt", nonce: 1 }
108+
console.log(hashSeries.peekHash()); // Generated hash value based on nonce + 1
109+
```
110+
111+
### HashChain({ seed, count, index })
112+
113+
This class is used to manage generating and iterating through a provable hash chain. It has the following methods:
114+
115+
- `state()`: Returns an object containing the `count`, `seed`, and `index` values.
116+
- `peek()`: Returns the next hash value in the chain based on the current `index`.
117+
- `get()`: Returns the current hash value in the chain based on the current `index`.
118+
- `next()`: Returns an object containing the next hash value in the chain, the `count`, and the updated `index`.
119+
- `last()`: Returns the previous hash value in the chain based on the current `index`.
120+
121+
```javascript
122+
const hashChain = new HashChain({ seed: "your-seed", count: 10 });
123+
console.log(hashChain.state()); // Generated state object
124+
console.log(hashChain.peek()); // Generated next hash value in the chain
125+
console.log(hashChain.get()); // Generated current hash value in the chain
126+
console.log(hashChain.next()); // Generated next hash value in the chain, count, and updated index
127+
console.log(hashChain.last()); // Generated previous hash value in the chain
128+
```
129+
130+
40131
## Additional Utilities
41132

42133
### defaults(state)
@@ -124,42 +215,6 @@ const randomInts = ints(byteGenerator, 10, 50, -25);
124215
console.log(randomInts); // Generated array of integer numbers
125216
```
126217

127-
### HashSeries({ seed, salt, nonce })
128-
129-
This class is used to generate a series of hashes based on the provided `seed`, `salt`, and `nonce` values. It has the following methods:
130-
131-
- `getHash()`: Returns the current hash value.
132-
- `next()`: Increments the `nonce` value and returns a new object with the updated `seed`, `salt`, and `nonce`.
133-
- `peekHash()`: Returns the next hash value based on the updated `nonce` value.
134-
- `calcHash(_seed, _salt, _nonce)`: Calculates the hash value using the provided `seed`, `salt`, and `nonce` values.
135-
- `state()`: Returns an object containing the `seed`, `salt`, and `nonce` values.
136-
137-
```javascript
138-
const hashSeries = new HashSeries({ seed: "your-seed", salt: "your-salt", nonce: 0 });
139-
console.log(hashSeries.getHash()); // Generated hash value
140-
console.log(hashSeries.next()); // { seed: "your-seed", salt: "your-salt", nonce: 1 }
141-
console.log(hashSeries.peekHash()); // Generated hash value based on nonce + 1
142-
```
143-
144-
### HashChain({ seed, count, index })
145-
146-
This class is used to manage generating and iterating through a provable hash chain. It has the following methods:
147-
148-
- `state()`: Returns an object containing the `count`, `seed`, and `index` values.
149-
- `peek()`: Returns the next hash value in the chain based on the current `index`.
150-
- `get()`: Returns the current hash value in the chain based on the current `index`.
151-
- `next()`: Returns an object containing the next hash value in the chain, the `count`, and the updated `index`.
152-
- `last()`: Returns the previous hash value in the chain based on the current `index`.
153-
154-
```javascript
155-
const hashChain = new HashChain({ seed: "your-seed", count: 10 });
156-
console.log(hashChain.state()); // Generated state object
157-
console.log(hashChain.peek()); // Generated next hash value in the chain
158-
console.log(hashChain.get()); // Generated current hash value in the chain
159-
console.log(hashChain.next()); // Generated next hash value in the chain, count, and updated index
160-
console.log(hashChain.last()); // Generated previous hash value in the chain
161-
```
162-
163218
## License
164219

165220
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

‎index.js‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,6 @@
1-
module.exports = require("./provable.js");
2-
module.exports.utils = require("./utils.js");
1+
module.exports = {
2+
Provable: require("./provable.js"),
3+
HashSeries: require("./hashSeries.js"),
4+
HashChain: require("./hashChain.js"),
5+
utils: require("./utils.js")
6+
}

‎test.js‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
const test = require("tape");
2-
const Provable = require("./provable");
3-
const { HashSeries, ChainSeries, HashChain } = require("./utils");
2+
const { Provable, HashChain, HashSeries} = require("./index");
3+
4+
console.log({
5+
Provable,
6+
HashChain,
7+
HashSeries
8+
})
49

510
let config = {
611
clientSeed: "bba625387fb64d772ff7da0ed6e71b16",

‎utils.js‎

Lines changed: 1 addition & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
const assert = require('assert')
21
const { v4: uuid } = require("uuid");
32
const lodash = require("lodash");
43
const crypto = require("crypto");
@@ -85,99 +84,6 @@ function ints(rng, count, max, min) {
8584
return result;
8685
}
8786

88-
function HashSeries({ seed = uuid(), salt = uuid(), nonce = 0 } = {}) {
89-
function calcHash(_seed = seed, _salt = salt, _nonce = nonce) {
90-
return crypto
91-
.createHmac("sha256", _seed)
92-
.update(`${_salt}:${_nonce}`)
93-
.digest("hex");
94-
}
95-
function getHash() {
96-
return calcHash(seed, salt, nonce);
97-
}
98-
function state() {
99-
return { seed, salt, nonce };
100-
}
101-
function next() {
102-
return {
103-
seed,
104-
salt,
105-
nonce: nonce + 1,
106-
};
107-
}
108-
function peekHash() {
109-
return calcHash(seed, salt, nonce + 1);
110-
}
111-
return {
112-
getHash,
113-
next,
114-
peekHash,
115-
calcHash,
116-
state,
117-
};
118-
}
119-
120-
// generate a provable hash chain count to -1
121-
function generateHashChain(count, seed) {
122-
assert(seed, "requires seed");
123-
assert(seed, "requires count");
124-
125-
var result = Array(count);
126-
127-
// generate chain in revese order
128-
for (var i = count - 1; i >= 0; i--) {
129-
seed = sha256(seed);
130-
result[i] = seed;
131-
}
132-
133-
return result;
134-
}
135-
136-
// manages generating and itteratng through a provable hashchain
137-
// the last hash of the previous chain will be used to generate the next.
138-
function HashChain({ seed = uuid(), count = 1000000, index = 0 }) {
139-
assert(count >= 1, "requires count");
140-
assert(seed, "requires seed");
141-
142-
const chain = generateHashChain(count, seed);
143-
144-
function state() {
145-
return { count, seed, index };
146-
}
147-
148-
function peek() {
149-
return chain[index + 1];
150-
}
151-
152-
function get() {
153-
return chain[index];
154-
}
155-
156-
function next() {
157-
const hash = peek();
158-
assert(hash, 'chain has ended')
159-
160-
// increment index and return hash
161-
return {
162-
hash,
163-
count,
164-
index: ++index,
165-
};
166-
}
167-
168-
function last() {
169-
return chain[index - 1];
170-
}
171-
172-
return {
173-
state,
174-
peek,
175-
get,
176-
next,
177-
last,
178-
};
179-
}
180-
18187
module.exports = {
18288
floats,
18389
bytesToFloat,
@@ -188,6 +94,4 @@ module.exports = {
18894
FloatGenerator,
18995
floatToInt,
19096
defaults,
191-
HashSeries,
192-
HashChain,
193-
};
97+
};

0 commit comments

Comments
 (0)