Skip to content

Commit e4d3552

Browse files
author
Dev Kalra
authored
[entropy] add sdk docs (#148)
* add sdk docs * pre commit * add copy
1 parent ddd99ff commit e4d3552

File tree

2 files changed

+93
-1
lines changed

2 files changed

+93
-1
lines changed
Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{
22
"protocol-design": "Protocol Design",
33
"best-practices": "Best Practices",
4-
"evm": "Entropy on EVM"
4+
"evm": "Entropy on EVM",
5+
"solidity-sdk": "Pyth Entropy Solidity SDK"
56
}
Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Pyth Entropy Solidity SDK
2+
3+
The Pyth Entropy Solidity SDK allows you to generate secure random numbers on the blockchain by
4+
interacting with the Pyth Entropy protocol.
5+
The SDK can be used for any application that requires random numbers, such as NFT mints, gaming, and more.
6+
7+
## Install
8+
9+
```shell copy
10+
npm install @pythnetwork/entropy-sdk-solidity
11+
```
12+
13+
## Setup
14+
15+
To use the SDK, you need the address of an Entropy contract on your blockchain and a randomness provider.
16+
You can find current deployments [here](evm.mdx).
17+
18+
Choose one of the networks and instantiate an `IEntropy` contract in your solidity contract:
19+
20+
```solidity copy
21+
IEntropy entropy = IEntropy(<address>);
22+
```
23+
24+
## Usage
25+
26+
To generate a random number, follow these steps.
27+
28+
### 1. Commit to a random number
29+
30+
Generate a 32-byte random number on the client side, then hash it with keccak256 to create a commitment.
31+
You can do this with typescript and web3.js as follows:
32+
33+
```typescript copy
34+
const randomNumber = web3.utils.randomHex(32);
35+
const commitment = web3.utils.keccak256(randomNumber);
36+
```
37+
38+
### 2. Request a number from Entropy
39+
40+
Invoke the `request` method of the `IEntropy` contract.
41+
The `request` method requires paying a fee in native gas tokens which is configured per-provider.
42+
Each entropy contracts has a default provider, you can get the default provider by calling the method `getDefaultProvider`.
43+
44+
```solidity copy
45+
address provider = entropy.getDefaultProvider();
46+
```
47+
48+
Use the `getFee` method to calculate the fee and send it as the value of the `request` call:
49+
50+
```solidity copy
51+
uint fee = entropy.getFee(provider);
52+
uint64 sequenceNumber = entropy.request{value: fee}(provider, commitment, true);
53+
```
54+
55+
This method returns a sequence number. Store this sequence number for use in later steps.
56+
If you are invoking this off-chain, the method also emits a `PythRandomEvents.Requested` event that contains the sequence number in it.
57+
58+
### 3. Fetch the provider's number
59+
60+
Providers store their uri, with some other metadata, on chain when registering and that can be fetched by calling the method `getProviderInfo`.
61+
You need the provider's uri to fetch the provider's random number.
62+
63+
For the provider `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` you can query the webservice at https://fortuna-staging.pyth.network :
64+
65+
```typescript copy
66+
await axios.get(
67+
`https://fortuna-staging.pyth.network/v1/chains/${chainName}/revelations/${sequenceNumber}`
68+
);
69+
```
70+
71+
This method returns a JSON object containing the provider's random number.
72+
73+
### 4. Reveal the number
74+
75+
Invoke the `reveal` method on the `IEntropy` contract:
76+
77+
```solidity copy
78+
bytes32 randomNumber = entropy.reveal(
79+
provider,
80+
sequenceNumber,
81+
randomNumber,
82+
providerRandomNumber
83+
)
84+
```
85+
86+
This method will combine the user and provider's random numbers, along with the blockhash, to construct the final secure random number.
87+
88+
## Example Application
89+
90+
The [Coin Flip](https://github.com/pyth-network/pyth-crosschain/tree/main/target_chains/ethereum/examples/coin_flip) example demonstrates how to build a smart contract that
91+
interacts with Pyth Entropy as well as a typescript client for that application.

0 commit comments

Comments
 (0)