[entropy] Typescript code for coin flip example + docs (#1128)

* adding stuff

* add coin flip example

* it works

* docs

* hm

* pr comments

package.json

@@ -15,6 +15,7 @@
  "target_chains/ethereum/entropy_sdk/solidity",
  "target_chains/ethereum/sdk/js",
  "target_chains/ethereum/sdk/solidity",
+ "target_chains/ethereum/examples/coin_flip/app",
  "target_chains/ethereum/examples/oracle_swap/app",
  "target_chains/sui/sdk/js",
  "target_chains/sui/cli",

target_chains/ethereum/entropy_sdk/solidity/README.md

@@ -0,0 +1,81 @@
+# 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.
+This SDK can be used for any application that requires random numbers, such as NFT mints, gaming, and more.
+
+**WARNING**: The Entropy protocol is currently in testnet. It is **NOT INTENDED** for use in production applications.
+Use this protocol at your own risk.
+
+## Install
+
+TODO
+
+## Setup
+
+To use the SDK, you need the address of an Entropy contract on your blockchain and a randomness provider.
+The following table lists the current deployments of entropy.
+
+| Chain | Entropy Address | Provider |
+| avalanche-fuji | 0xD42c7a708E74AD19401D907a14146F006c851Ee3 | 0x368397bDc956b4F23847bE244f350Bde4615F25E
+| optimism-goerli | 0x28F16Af4D87523910b843a801454AEde5F9B0459 | 0x368397bDc956b4F23847bE244f350Bde4615F25E
+| eos-evm-testnet | 0xD42c7a708E74AD19401D907a14146F006c851Ee3 | 0x368397bDc956b4F23847bE244f350Bde4615F25E
+
+Choose one of these networks and instantiate an `IEntropy` contract in your solidity contract:
+
+```solidity
+ 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
+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:
+
+```solidity
+uint64 sequenceNumber = entropy.request(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
+
+Fetch the provider's random number from them.
+For the provider `0x368397bDc956b4F23847bE244f350Bde4615F25E` you can query the webservice at https://fortuna-staging.pyth.network :
+
+```typescript
+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
+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.