Add JSDoc Description/Param documentration

DOCUMENTATION.md

@@ -15,6 +15,17 @@ Helping with both **low-level calculations** and **higher-order computations**,
 
 [![Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.gg/JFBPMxv5tr)
 
+### Namespaces
+
+- [calculate](calculate)
+- [compute](compute)
+- [core](core)
+- [utils](utils)
+
+**Core**
+- [encodeWinningPicks](core#encodeWinningPicks)
+- [winningPicks](core#winningPicks)
+
 **Calculate**
 - [calculateCardinality](calculate#calculatecardinality)
 - [calculateFractionOfPrize](calculate#calculatefractionofprize)

docs/md/calculate.md

@@ -4,16 +4,16 @@
 
 ### Functions
 
-- [calculateCardinality](#calculatecardinality)
-- [calculateFractionOfPrize](#calculatefractionofprize)
-- [calculateNormalizedBalancePicksFromTotalPicks](#calculatenormalizedbalancepicksfromtotalpicks)
-- [calculateNumberOfMatches](#calculatenumberofmatches)
-- [calculateNumberOfPrizesForTierIndex](#calculatenumberofprizesfortierindex)
-- [calculatePick](#calculatepick)
-- [calculatePicks](#calculatepicks)
-- [calculatePicksFromAverageTotalSuppliesBetween](#calculatepicksfromaveragetotalsuppliesbetween)
-- [calculatePrizeForTierPercentage](#calculateprizefortierpercentage)
-- [calculateTierIndexFromMatches](#calculatetierindexfrommatches)
+- [calculateCardinality](calculate.md#calculatecardinality)
+- [calculateFractionOfPrize](calculate.md#calculatefractionofprize)
+- [calculateNormalizedBalancePicksFromTotalPicks](calculate.md#calculatenormalizedbalancepicksfromtotalpicks)
+- [calculateNumberOfMatches](calculate.md#calculatenumberofmatches)
+- [calculateNumberOfPrizesForTierIndex](calculate.md#calculatenumberofprizesfortierindex)
+- [calculatePick](calculate.md#calculatepick)
+- [calculatePicks](calculate.md#calculatepicks)
+- [calculatePicksFromAverageTotalSuppliesBetween](calculate.md#calculatepicksfromaveragetotalsuppliesbetween)
+- [calculatePrizeForTierPercentage](calculate.md#calculateprizefortierpercentage)
+- [calculateTierIndexFromMatches](calculate.md#calculatetierindexfrommatches)
 
 ## Functions
 
@@ -35,7 +35,7 @@
 
 #### Defined in
 
-[calculate/calculateCardinality.ts:6](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculateCardinality.ts#L6)
+[calculate/calculateCardinality.ts:6](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculateCardinality.ts#L6)
 
 ___
 
@@ -56,7 +56,7 @@ ___
 
 #### Defined in
 
-[calculate/calculateFractionOfPrize.ts:4](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculateFractionOfPrize.ts#L4)
+[calculate/calculateFractionOfPrize.ts:4](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculateFractionOfPrize.ts#L4)
 
 ___
 
@@ -77,7 +77,7 @@ ___
 
 #### Defined in
 
-[calculate/calculateNormalizedBalancePicksFromTotalPicks.ts:3](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculateNormalizedBalancePicksFromTotalPicks.ts#L3)
+[calculate/calculateNormalizedBalancePicksFromTotalPicks.ts:3](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculateNormalizedBalancePicksFromTotalPicks.ts#L3)
 
 ___
 
@@ -100,7 +100,7 @@ ___
 
 #### Defined in
 
-[calculate/calculateNumberOfMatches.ts:5](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculateNumberOfMatches.ts#L5)
+[calculate/calculateNumberOfMatches.ts:5](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculateNumberOfMatches.ts#L5)
 
 ___
 
@@ -121,7 +121,7 @@ ___
 
 #### Defined in
 
-[calculate/calculateNumberOfPrizesForTierIndex.ts:1](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculateNumberOfPrizesForTierIndex.ts#L1)
+[calculate/calculateNumberOfPrizesForTierIndex.ts:1](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculateNumberOfPrizesForTierIndex.ts#L1)
 
 ___
 
@@ -142,7 +142,7 @@ ___
 
 #### Defined in
 
-[calculate/calculatePick.ts:6](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculatePick.ts#L6)
+[calculate/calculatePick.ts:6](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculatePick.ts#L6)
 
 ___
 
@@ -163,7 +163,7 @@ ___
 
 #### Defined in
 
-[calculate/calculatePicks.ts:6](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculatePicks.ts#L6)
+[calculate/calculatePicks.ts:6](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculatePicks.ts#L6)
 
 ___
 
@@ -185,7 +185,7 @@ ___
 
 #### Defined in
 
-[calculate/calculatePicksFromAverageTotalSuppliesBetween.ts:7](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculatePicksFromAverageTotalSuppliesBetween.ts#L7)
+[calculate/calculatePicksFromAverageTotalSuppliesBetween.ts:7](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculatePicksFromAverageTotalSuppliesBetween.ts#L7)
 
 ___
 
@@ -208,7 +208,7 @@ ___
 
 #### Defined in
 
-[calculate/calculatePrizeForTierPercentage.ts:6](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculatePrizeForTierPercentage.ts#L6)
+[calculate/calculatePrizeForTierPercentage.ts:6](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculatePrizeForTierPercentage.ts#L6)
 
 ___
 
@@ -229,4 +229,5 @@ ___
 
 #### Defined in
 
-[calculate/calculateTierIndexFromMatches.ts:1](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/calculate/calculateTierIndexFromMatches.ts#L1)
+[calculate/calculateTierIndexFromMatches.ts:1](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/calculate/calculateTierIndexFromMatches.ts#L1)
+es.ts#L1)

docs/md/compute.md

@@ -4,14 +4,14 @@
 
 ### Functions
 
-- [computeDrawResults](compute.md#computedrawresults)
-- [computePickPrize](compute.md#computepickprize)
-- [computePicksPrizes](compute.md#computepicksprizes)
-- [computePrizeAmount](compute.md#computeprizeamount)
-- [computePrizeDistributionFromTicketAverageTotalSupplies](compute.md#computeprizedistributionfromticketaveragetotalsupplies)
-- [computeUserPicks](compute.md#computeuserpicks)
-- [computeUserWinningPicksForRandomNumber](compute.md#computeuserwinningpicksforrandomnumber)
-- [computeWinningPicks](compute.md#computewinningpicks)
+- [computeDrawResults](compute#computedrawresults)
+- [computePickPrize](compute#computepickprize)
+- [computePicksPrizes](compute#computepicksprizes)
+- [computePrizeAmount](compute#computeprizeamount)
+- [computePrizeDistributionFromTicketAverageTotalSupplies](compute#computeprizedistributionfromticketaveragetotalsupplies)
+- [computeUserPicks](compute#computeuserpicks)
+- [computeUserWinningPicksForRandomNumber](compute#computeuserwinningpicksforrandomnumber)
+- [computeWinningPicks](compute#computewinningpicks)
 
 ## Functions
 
@@ -36,7 +36,7 @@
 
 #### Defined in
 
-[compute/computeDrawResults.ts:10](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/compute/computeDrawResults.ts#L10)
+[compute/computeDrawResults.ts:10](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/compute/computeDrawResults.ts#L10)
 
 ___
 
@@ -61,7 +61,7 @@ ___
 
 #### Defined in
 
-[compute/computePickPrize.ts:8](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/compute/computePickPrize.ts#L8)
+[compute/computePickPrize.ts:8](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/compute/computePickPrize.ts#L8)
 
 ___
 
@@ -86,7 +86,7 @@ ___
 
 #### Defined in
 
-[compute/computePicksPrizes.ts:6](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/compute/computePicksPrizes.ts#L6)
+[compute/computePicksPrizes.ts:6](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/compute/computePicksPrizes.ts#L6)
 
 ___
 
@@ -109,7 +109,7 @@ ___
 
 #### Defined in
 
-[compute/computePrizeAmount.ts:8](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/compute/computePrizeAmount.ts#L8)
+[compute/computePrizeAmount.ts:8](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/compute/computePrizeAmount.ts#L8)
 
 ___
 
@@ -133,7 +133,7 @@ ___
 
 #### Defined in
 
-[compute/computePrizeDistributionFromTicketAverageTotalSupplies.ts:12](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/compute/computePrizeDistributionFromTicketAverageTotalSupplies.ts#L12)
+[compute/computePrizeDistributionFromTicketAverageTotalSupplies.ts:12](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/compute/computePrizeDistributionFromTicketAverageTotalSupplies.ts#L12)
 
 ___
 
@@ -155,7 +155,7 @@ ___
 
 #### Defined in
 
-[compute/computeUserPicks.ts:10](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/compute/computeUserPicks.ts#L10)
+[compute/computeUserPicks.ts:10](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/compute/computeUserPicks.ts#L10)
 
 ___
 
@@ -182,7 +182,7 @@ ___
 
 #### Defined in
 
-[compute/computeUserWinningPicksForRandomNumber.ts:11](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/compute/computeUserWinningPicksForRandomNumber.ts#L11)
+[compute/computeUserWinningPicksForRandomNumber.ts:11](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/compute/computeUserWinningPicksForRandomNumber.ts#L11)
 
 ___
 
@@ -204,4 +204,6 @@ ___
 
 #### Defined in
 
-[compute/computeWinningPicks.ts:4](https://github.com/pooltogether/v4-utils-js/blob/4a945a2/src/compute/computeWinningPicks.ts#L4)
+[compute/computeWinningPicks.ts:4](https://github.com/pooltogether/v4-utils-js/blob/e8b45cf/src/compute/computeWinningPicks.ts#L4)
+puteWinningPicks.ts#L4)
+ks.ts#L4)

docs/md/core.md

@@ -0,0 +1,60 @@
+#  core
+
+## Table of contents
+
+### Functions
+
+- [encodeWinningPicks](core#encodewinningpicks)
+- [winningPicks](core#winningpicks)
+
+## Functions
+
+### encodeWinningPicks
+
+▸ **encodeWinningPicks**(`user`, `drawResults`): `Claim`
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `user` | `User` |
+| `drawResults` | `DrawResults`[] |
+
+#### Returns
+
+`Claim`
+
+#### Defined in
+
+core/encodeWinningPicks.ts:7
+
+___
+
+### winningPicks
+
+▸ **winningPicks**(`user`, `draws`, `prizeDistributions`): `Claim`
+
+**`description`** Computes a User's winning picks for multiple Draws and returns an encoded transaction.
+
+**`dev`** Historical blockchain state must be first fetched to run computations.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `user` | `User` | Includes an account address and a list of normalized balances. |
+| `draws` | `Draw`[] | Draw(s) should be fetched from DrawHistory contract |
+| `prizeDistributions` | `PrizeDistribution`[] | PrizeDistribution(s) should be fetched from PrizeTierHistory contract |
+
+#### Returns
+
+`Claim`
+
+Computed winning picks and encoded transaction ready for broadcast to an EVM blockchain.
+
+#### Defined in
+
+core/winningPicks.ts:13
+ts:13
+:13
+ts:13

docs/md/index.md

@@ -15,7 +15,18 @@ Helping with both **low-level calculations** and **higher-order computations**,
 
 [![Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.gg/JFBPMxv5tr)
 
-Calculate
+### Namespaces
+
+- [calculate](calculate)
+- [compute](compute)
+- [core](core)
+- [utils](utils)
+
+**Core**
+- [encodeWinningPicks](core#encodeWinningPicks)
+- [winningPicks](core#winningPicks)
+
+**Calculate**
 - [calculateCardinality](calculate#calculatecardinality)
 - [calculateFractionOfPrize](calculate#calculatefractionofprize)
 - [calculateNormalizedBalancePicksFromTotalPicks](calculate#calculatenormalizedbalancepicksfromtotalpicks)
@@ -27,7 +38,7 @@ Calculate
 - [calculatePrizeForTierPercentage](calculate#calculateprizefortierpercentage)
 - [calculateTierIndexFromMatches](calculate#calculatetierindexfrommatches)
 
-### Compute
+**Compute**
 - [computeDrawResults](compute#computedrawresults)
 - [computePickPrize](compute#computepickprize)
 - [computePicksPrizes](compute#computepicksprizes)
@@ -37,7 +48,7 @@ Calculate
 - [computeUserWinningPicksForRandomNumber](compute#computeuserwinningpicksforrandomnumber)
 - [computeWinningPicks](compute#computewinningpicks)
 
-### Utilities
+**Utilities**
 - [createDrawResultsObject](utils#createdrawresultsobject)
 - [filterResultsByValue](utils#filterresultsbyvalue)
 - [findBitMatchesAtIndex](utils#findbitmatchesatindex)
@@ -52,7 +63,7 @@ Calculate
 - [sumTwoBigNumbers](utils#sumtwobignumbers)
 - [updateDrawResultsWithWinningPicks](utils#updatedrawresultswithwinningpicks)
 
-## Installation
+## 💾  Installation
 
 This project is available as an NPM package:
 
@@ -70,9 +81,9 @@ The repo can be cloned from Github for contributions.
 git clone https://github.com/pooltogether/v4-utils-js
 ```
 
-## Quickstart 🏎️ 
+## 🏎️  Quickstart 
 
-Draw and PrizeDistrubtion structs should be fetched using the [v4-js-client](https://github.com/pooltogether/v4-js-client) node module.
+Draw and PrizeDistribution structs should be fetched using the [@pooltogether/v4-js-client](/protocol/libraries/v4-js-client/) node module.
 
 ### Winnings Picks
 ```ts
@@ -89,29 +100,33 @@ const transaction = encodeWinningPicks(wallet.address, computedWinningPicks);
 wallet.send(transaction.encodedWinningPickIndices)
 ```
 
-## Low-Level Calculations & Computations
+## 🧮  Examples
 
 The utility library simulates smart contract rules/operations and also encapsulates higher-level abstractions common to PoolTogether V4 required transactions.
 
 For example, in the `DrawCalculator` smart contract an account `address` is used to generate a random number via the `keccak256` hashing function. The hashed address is subquentially encoded with a `pickIndices` to calculate a `randomNumber`. Using a depositors `normalizedBalance` and `totalPrizeDistributionPicks` we can find the ceiling for the number of picks to calculate for each Draw epoch timerange.
 
 In other words, the library exposes low-level functions like `hashUserAddress` and `calculateNumberOfMatches` so it's easier to build the high-level abstractions, like `winningPicks` which simply takes a user address, plus historical Draw/PrizeDistribution structs and generates/encode all potential winning picks for a user into a single transaction.
 
-### Compute User Picks ([calculateNumberOfMatches](protocol/libraries/v4-utils-js/calculate#calculatenumberofmatches))
+### Compute User Picks ([computeUserPicks](/protocol/libraries/v4-utils-js/compute#computeuserpicks))
 Calculates a depositor potential picks using the totalNumberOfPicks relative to the normalizedBalance.
 
 ```ts
 import { parseEther } from '@ethersproject/units';
 import { computeUserPicks } from '@pooltogether/v4-utils-js';
 
+const totalPicks = parseUnits('1000', 18);
+const address = '0x000.000';
+const normalizedBalance = parseUnits('0.1', 18)
+
 const userPicksByIndexAndHash = computeUserPicks(
+    totalPicks,
     address,
-    parseUnits('1000', 18)
-    parseUnits('0.1', 18)
+    normalizedBalance
 );
 ```
 
-### Calculate Number of Matches
+### Calculate Number of Matches ([calculateNumberOfMatches](/protocol/libraries/v4-utils-js/calculate#calculatenumberofmatches))
 
 A user's pick number and the Draw random generated number are compared to compute winning picks.