[entropy] add sdk docs (#148)

* add sdk docs

* pre commit

* add copy

Author: Dev Kalra

pages/documentation/entropy/_meta.json

@@ -1,5 +1,6 @@
 {
   "protocol-design": "Protocol Design",
   "best-practices": "Best Practices",
-  "evm": "Entropy on EVM"
+  "evm": "Entropy on EVM",
+  "solidity-sdk": "Pyth Entropy Solidity SDK"
 }

pages/documentation/entropy/solidity-sdk.mdx

@@ -0,0 +1,91 @@
+# Pyth Entropy Solidity SDK
+
+The Pyth Entropy Solidity SDK allows you to generate secure random numbers on the blockchain by
+interacting with the Pyth Entropy protocol.
+The SDK can be used for any application that requires random numbers, such as NFT mints, gaming, and more.
+
+## Install
+
+```shell copy
+npm install @pythnetwork/entropy-sdk-solidity
+```
+
+## Setup
+
+To use the SDK, you need the address of an Entropy contract on your blockchain and a randomness provider.
+You can find current deployments [here](evm.mdx).
+
+Choose one of the networks and instantiate an `IEntropy` contract in your solidity contract:
+
+```solidity copy
+ IEntropy entropy = IEntropy(<address>);
+```
+
+## Usage
+
+To generate a random number, follow these steps.
+
+### 1. Commit to a random number
+
+Generate a 32-byte random number on the client side, then hash it with keccak256 to create a commitment.
+You can do this with typescript and web3.js as follows:
+
+```typescript copy
+const randomNumber = web3.utils.randomHex(32);
+const commitment = web3.utils.keccak256(randomNumber);
+```
+
+### 2. Request a number from Entropy
+
+Invoke the `request` method of the `IEntropy` contract.
+The `request` method requires paying a fee in native gas tokens which is configured per-provider.
+Each entropy contracts has a default provider, you can get the default provider by calling the method `getDefaultProvider`.
+
+```solidity copy
+address provider = entropy.getDefaultProvider();
+```
+
+Use the `getFee` method to calculate the fee and send it as the value of the `request` call:
+
+```solidity copy
+uint fee = entropy.getFee(provider);
+uint64 sequenceNumber = entropy.request{value: fee}(provider, commitment, true);
+```
+
+This method returns a sequence number. Store this sequence number for use in later steps.
+If you are invoking this off-chain, the method also emits a `PythRandomEvents.Requested` event that contains the sequence number in it.
+
+### 3. Fetch the provider's number
+
+Providers store their uri, with some other metadata, on chain when registering and that can be fetched by calling the method `getProviderInfo`.
+You need the provider's uri to fetch the provider's random number.
+
+For the provider `0x6CC14824Ea2918f5De5C2f75A9Da968ad4BD6344` you can query the webservice at https://fortuna-staging.pyth.network :
+
+```typescript copy
+await axios.get(
+  `https://fortuna-staging.pyth.network/v1/chains/${chainName}/revelations/${sequenceNumber}`
+);
+```
+
+This method returns a JSON object containing the provider's random number.
+
+### 4. Reveal the number
+
+Invoke the `reveal` method on the `IEntropy` contract:
+
+```solidity copy
+bytes32 randomNumber = entropy.reveal(
+    provider,
+    sequenceNumber,
+    randomNumber,
+    providerRandomNumber
+)
+```
+
+This method will combine the user and provider's random numbers, along with the blockhash, to construct the final secure random number.
+
+## Example Application
+
+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
+interacts with Pyth Entropy as well as a typescript client for that application.