essential-eth 0.4.9 → 0.5.0

package/readme.md

@@ -1,9 +1,11 @@
 <p align="center">
-  <a><img src="https://user-images.githubusercontent.com/3408480/161474132-ae95d289-2298-46f1-b48d-9c02d88f7e38.png" title="Logo" height="400" /></a>
+  <img src="https://user-images.githubusercontent.com/3408480/163274699-ae4fb0f4-fca0-4745-bcd7-4868f80deaf6.png" title="Logo"/>
+
 </p>
 <p align="center">
+
   <b>
-    Essential Eth
+    🪶 Essential Eth 🪶
   </b>
   <br/>
   <i>A replacement for ethers & web3 that's 50x smaller</i>
@@ -20,18 +22,14 @@
 <img src="https://user-images.githubusercontent.com/3408480/133322814-f3d18424-4ba8-4a37-8cbc-c5e6828354a3.png" title="Import size comparison" width="900"/>
 </p>
 
-![Screen Shot 2022-01-12 at 10 25 29 AM](https://user-images.githubusercontent.com/3408480/149190699-9bc15719-9382-46af-a77b-45e138f37643.png)
-
-![Screen Shot 2022-01-12 at 10 24 57 AM](https://user-images.githubusercontent.com/3408480/149190691-ed2913b9-8c14-4a8e-b5f8-0895fbac279b.png)
-
 ---
 
 <br/>
 
-- ⚡️ A replacement for `web3` and `ethers`
-- 🏎 [The TINIEST code size possible](https://bundlephobia.com/package/essential-eth)
+- 🏆️ <sub><sup>[smallest code size possible](https://bundlephobia.com/package/essential-eth)</sup></sub>
 - ʦ Fully typed with TypeScript (also works with JavaScript)
 - 🧪 Tested to match both `web3` and `ethers`
+- - ⚡️ Near-identical API to `ethers`
 - 🌲 Tree-shaking and no side-effects
 - 🙌 Supports multiple JS versions (CommonJS and ESM)
   - ✅ Node 17, 16, 14, & 12
@@ -39,16 +37,6 @@
 
 <br/>
 
-## More Info
-
-🧪 This repo is under active development. The API is less-fully featured than `web3` and `ethers`. More functions added often!
-
-![](https://badgen.net/bundlephobia/minzip/essential-eth) ![](https://badgen.net/bundlephobia/tree-shaking/essential-eth) ![](https://img.shields.io/npm/v/essential-eth) ![](https://badgen.net/bundlephobia/dependency-count/essential-eth)
-
-👨🏻‍💻 Breaking changes will exist between minor versions until `1.0.0` (Versions go `major.minor.patch`)
-
-<br/>
-
 ## Install
 
 ```sh
@@ -126,6 +114,56 @@ weiToEther('1000000000000000000').toNumber();
 
 <br/>
 
+#### `gweiToEther`
+
+```typescript
+gweiToEther(gweiQuantity: string | number | TinyBig | Big): TinyBig
+```
+
+<details>
+  <summary>View Example</summary>
+
+```typescript
+import { gweiToEther } from 'essential-eth';
+
+gweiToEther(1000000000).toString();
+// "1"
+
+gweiToEther(1000000000).toNumber();
+// 1
+gweiToEther('1000000000').toNumber();
+// 1
+```
+
+</details>
+
+<br/>
+
+#### `etherToGwei`
+
+```typescript
+etherToGwei(etherQuantity: string | number | TinyBig | Big): TinyBig
+```
+
+<details>
+  <summary>View Example</summary>
+
+```typescript
+import { etherToGwei } from 'essential-eth';
+
+etherToGwei(0.000000001).toString();
+// "1"
+
+etherToGwei(0.000000001).toNumber();
+// 1
+etherToGwei('0.000000001').toNumber();
+// 1
+```
+
+</details>
+
+<br/>
+
 #### `toChecksumAddress`
 
 ```typescript
@@ -177,6 +215,35 @@ isAddress('vitalik.eth');
 
 <br/>
 
+#### `hexZeroPad`
+
+```typescript
+// returns a hex string padded to a specified length of bytes
+// if the hex value provided is already longer than the padding value, the value itself is returned without alteration
+hexZeroPad(hexValue: string | number, length: number): string
+```
+
+<details>
+  <summary>View Example</summary>
+
+```typescript
+import { hexZeroPad } from 'essential-eth';
+
+hexZeroPad('0x60', 2);
+// '0x0060'
+
+hexZeroPad(0x60, 3);
+// '0x000060'
+
+// Length of string is already longer than padding value
+hexZeroPad('0x31323334', 3);
+// Throws error
+```
+
+</details>
+
+<br/>
+
 ## RPC
 
 ```typescript
@@ -214,6 +281,33 @@ provider.getGasPrice().toNumber();
 
 <br/>
 
+#### `getBalance`
+
+Returns the balance of an address at a given block
+
+```typescript
+// Same API as ethers.providers.getBalance
+// Same API as web3.eth.getBalance
+getBalance(address: string, blockTag?: BlockTag): Promise<TinyBig>
+```
+
+<details>
+  <summary>View Example</summary>
+
+```typescript
+import { JsonRpcProvider } from 'essential-eth';
+
+const provider = new JsonRpcProvider();
+await provider
+  .getBalance('0x7cB57B5A97eAbe94205C07890BE4c1aD31E486A8')
+  .then((balance) => console.log(balance.toString()));
+// "28798127851528138"
+```
+
+</details>
+
+<br/>
+
 #### `getNetwork`
 
 Returns a Network
@@ -267,49 +361,182 @@ essentialEth.getBlock('latest');
 
 /*
 {
-"baseFeePerGas": "0xf639de71c",
-"extraData": "0x4b75436f696e506f6f6c201360d0ff24ef3c3c",
-"gasLimit": 30000000,
-"gasUsed": 1344062,
-"hash": "0xd61a202c828a67085a08a69c4b1e5e096781d7169eaccb47be26147a15145f38",
-"logsBloom": "0x00a001060000000000a00000800810010600000040100000000200000020000000c800000000000000004a8000000101020080100800200040400000102061080000048000000918c800400c0800406000000000004010000440120080200008820009000800000004001804000000000041802010000400008200900808a010110000416010201100900008010480050000100101400008040010420010200002101240000020800000008080000000406000880000003000200602100200000001000260000240240000800020100400200000000a0010001000020680000000102008080081400004000800000004000000212000c0500148089002000000",
-"miner": "0xd757fd54b273BB1234d4d9993f27699d28d0EDD2",
-"mixHash": "0x363138be56fd5304ca6f0ce56d24d6469f4a5a88c771da1ddf7e69fb23c7d599",
-"nonce": "0xdb88082877e8b003",
-"number": 13402040,
-"parentHash": "0xfb7ef17413a17f07791301897f406a05eb3e99acb495bf3bab146a30af5615eb",
-"receiptsRoot": "0xfc35fd7463baadc116202ef7a87ddba23a80bd277dd44a4bd3a2b2f48b469be8",
-"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
-"size": 7672,
-"stateRoot": "0x8fef1cb4b33ce55f43e8d3e2d19a6db55a8311aead0a25b359eef4d6e8ab6870",
-"timestamp": 1634019741,
-"transactions": Array [
-"0x4b5ee005588efa1881d4bdd97c20fb1b311896bd150a62f0379256c12b4d3243",
-"0xe28945b5b7bb1963e765b117a88b2fd785ef751bb141fbdf03435994ebd22383",
-"0xb15b9d44303f0f7a10e5c27320421aa790e12af6bb4f300963da43d5c2ad3a3c",
-"0x67296bb97ab2accb35b9b73d2fb856f7f28081a469b8ff7e17a89799af9fb729",
-"0xe8530f6c51c4efe9e15bdcc90b5f879895e0f6682de543c92c5d3d09ec149bd7",
-"0xbbefd1fc51bac8e10998ccfa2601643a063c68c16cf4b6a91756936084849f36",
-"0x37c8ae4037b833936163b22c17f39f11169fbeb2cfc249830b0514411d2a2859",
-"0xe47b2ba6979470bc5aa6529fda7969e0758b3123a91b65d9da49b133f196eaa6",
-"0x738d2ca35f180a42af6407cb2b724b0c589168740a39e7e1719e30c644766a55",
-"0x60df73109fc534c3a2126df1a4ed4cb4946a188bb6d34a49025ec4e41d0ee601",
-"0xaf51a25e70321b5c8987acb3e4a2d5e9e8869f9bb74303984e56c37090dbd8ba",
-"0xb42bd613800595b21717ea55ea5c2390ffe0ba12297aae0811f6938fbd86c605",
-"0x628d637eae8f3bf4c3867fffadfb6c6f09228f0d037abc921d30cb4a7e28fa57",
-"0xf6f19b03636250610e9a724eff7b265cbeed737b0a018500ebbe91e3aaf9ebaf",
-"0x2376f3a78b63d482d4edcfd7903faeaee49e95b0fb12894f49e6c0ed6709d51a",
-"0xbbc5634af5882ec73d713f6a3c34a6ff6915c18ab445c9c6d5ff1fb185dcb2d2",
-"0x15349a7d15861d7f50310a392397a3c7c43a19d70c5543738943b6222460633a",
-"0x2a166ca1491a05decf2c107050877c62e194c3bdc95a72de79acb39271ebfea1",
-"0x55efd630c466b58e2051afb55f66f8f415c93c330c7e48e439f0667cf67407c1",
-"0xbd095088949d323b4ab7cbeeba2534693c14d2a9c25e923bf87cd5c1edfce00a",
-"0xeb4f9d928020962c6a13ac7de0fb09d0d5c0a0064060d11f2e8cebc6d60443f0",
-"0x482fb59cef1804ff20752c50b737ab44b4db942e7816d4ff38827109f79c5b6c",
-"0xf0d87f44454bf2f2d23c72c775ca9051848bf8fe4ce293c8d0a7160a5c7b366d",
-],
-"transactionsRoot": "0x7fd87cbada35409e8a235c7d087d8bb7af6cfa0c7985d825ca69851b4192879f",
-"uncles": Array [],
+        number: 4232826,
+        hash: '0x93211a1cd17e154b183565ec685254a03f844a8e34824a46ce1bdd6753dcb669',
+        parentHash: '0x1b32bfcba1bb2a57f56e166a3bb06875a1978992999dfc8828397b4c1526f472',
+        sha3Uncles: '0x0fb399c67bb5a071ec8a22549223215ab76b7d4009941c9c37aa3c3936010463',
+        logsBloom: '0x00000000000000000000101000000000020000000000000000000000000000000000400000010000000000000000000000000000010000000008800000000800000000200000000000000000000000000000000000000000000002000000000000000000000000000040000000000040000000000000000000000000000000000000000000000001000000000004000000000010000000000000000020000000000000000200100020000000000000000080000000000080001000000000000000000001040000000000000000008000000020010100000000200000100000000000000000000000002000000080000000020400000000002000200000000000',
+        transactionsRoot: '0xc43b3f13e1fe810e34d3a26ffe465b72c7063a5c70a02de2c78e91e4d10bd9fb',
+        stateRoot: '0x04d7bc816537ea7ef3a16e76c9879d29f34f99d4154273c2e98e012a31bad745',
+        receiptsRoot: '0x89c6f781ceac0bd49c4d9aa9115df4a5d4dd0e0220ff7668012f15bc04222c6b',
+        miner: '0x31fe561eb2c628cD32Ec52573D7c4b7E4C278Bfa',
+        difficulty: '1300907486001755331049',
+        totalDifficulty: '5989929395521171616186006183',
+        extraData: '0xce018c495249532d62613031656132',
+        size: 5416,
+        gasLimit: 6800000,
+        gasUsed: 202955,
+        timestamp: 1649884910,
+        transactions: [
+          '0x6b34a59c7b9aead24fa6dad782f8a3ad84ed4a23ee09bcbf0bcf880840fbbe20',
+          '0x9a3851ca24d5336c6a0d48aba2c4b4769d7a672c9b01729c5eb9924efd1b19a7',
+          '0xc3ed3d198b62f2f3427ebfa3bbd0fcada4e3c0c189e4464e7eeceb403c75981e'
+        ],
+        uncles: [
+          '0x0c567c054e98153f10d651fbbc018891c1dd9d62a9ffd998e87678803e95b6ed',
+          '0xb7d69389dbfb057c6fcb4bc0582d46a2ba01170703f0dadf8cd1462b83e88753',
+          '0xd5f74ccd0ad4c58b3161e8c2c507c264231e5f28925061b809c02e5e4bb6db28'
+        ],
+        minimumGasPrice: '0x387ee40',
+        bitcoinMergedMiningHeader: '0x04000020e8567ed3d2480e15a1dd1b4335e4732ae343c037e4fd03000000000000000000ed10a8340d163d3e813bdd430f902f4e5a56828dc62313b2e23797c0be6b8516eb3e576297d8091735884f42',
+        bitcoinMergedMiningCoinbaseTransaction: '0x0000000000000140e910128fda7bac502dc5e0573bbaf12de8e2524f70c22f7bd160dedcb19a2521002b6a2952534b424c4f434b3ae493303f597fa368c0ccc4f8aceabf1c315bb7c9a07605c073a89f260040967aace6a7d9',
+        bitcoinMergedMiningMerkleProof: '0xdf63a3d7eb6fbcfb301311faa46e9a15b0408bb1a04e284daee86c273c1dfd65ede23f3170f806e9e0f4cef7ba6b56aa37470d9c23f96ec8e43d08b58645919c5e10bcb892897a731f8f9ce79c72dc0e390896bcd6c67bb38c0bdb72982b6cf05519968d76673572c3f3ef3a08b0ddb464863f1788f7cdbaad3fe44a8a8af576d430ac282fe28852c16df198ca96cc5f71a50695912efe1a836e8442be69e31b6d6f973da2818bce9a3a1c2d9be0671aee9a7776e398d6a03d1e178e20d84646004a3d03c0501334e629d9146aa6a01316dcbaa289df6e6c5e3090cadaddff22699cfc7ff09512fc0d65c5062f17c98561ce3c9510de210d9d654cf99f8d756ff37c9fa21e7122ee8cadb923341690845d572921425f2bd7e044558b7e07983ac4df28928028b0c13c3624dc7a965af8091b0cecc845bf7da5308c03b2c97d607f6706a599f802025894435f1d76ea4e67cc2fc4e1559f1206f559a24633de0f',
+        hashForMergedMining: '0xe493303f597fa368c0ccc4f8aceabf1c315bb7c9a07605c073a89f260040967a',
+        paidFees: '0xc0744dcb7a0',
+        cumulativeDifficulty: '0x1190930db285269e582'
+      }
+*/
+```
+
+</details>
+
+<br/>
+
+#### `getTransaction`
+
+Returns the Transaction associated with a given hash
+
+```typescript
+// Similar to ethers.provider.getTransaction, formatting may differ
+getTransaction(hash: string): Promise<Transaction>
+```
+
+<details>
+  <summary>View Example</summary>
+
+```typescript
+import { JsonRpcProvider } from 'essential-eth';
+const essentialEth = new JsonRpcProvider();
+await provider.getTransaction(
+  '0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789',
+);
+
+/*
+   {
+      accessList: [],
+      blockHash: '0x876810a013dbcd140f6fd6048c1dc33abbb901f1f96b394c2fa63aef3cb40b5d',
+      blockNumber: 14578286,
+      chainId: 1,
+      from: '0xdfD9dE5f6FA60BD70636c0900752E93a6144AEd4',
+      gas: Big {
+        s: 1,
+        e: 5,
+        c: [ 1, 1, 2, 1, 6, 3 ],
+        constructor: <ref *1> [Function: Big] {
+          DP: 20,
+          RM: 1,
+          NE: -7,
+          PE: 21,
+          strict: false,
+          roundDown: 0,
+          roundHalfUp: 1,
+          roundHalfEven: 2,
+          roundUp: 3,
+          Big: [Circular *1],
+          default: [Circular *1]
+        }
+      },
+      gasPrice: Big {
+        s: 1,
+        e: 10,
+        c: [
+          4, 8, 5, 9, 2,
+          4, 2, 6, 8, 5,
+          8
+        ],
+        constructor: <ref *1> [Function: Big] {
+          DP: 20,
+          RM: 1,
+          NE: -7,
+          PE: 21,
+          strict: false,
+          roundDown: 0,
+          roundHalfUp: 1,
+          roundHalfEven: 2,
+          roundUp: 3,
+          Big: [Circular *1],
+          default: [Circular *1]
+        }
+      },
+      hash: '0x9014ae6ef92464338355a79e5150e542ff9a83e2323318b21f40d6a3e65b4789',
+      input: '0x83259f170000000000000000000000000000000000000000000000000000000000000080000000000000000000000000dfd9de5f6fa60bd70636c0900752e93a6144aed400000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000024000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000009e99ad11a214fd016b19dc3648678c5944859ae292b21c24ca94f857836c4596f1950c82dd0c23dd621af4763edc2f66466e63c5df9de0c1107b1cd16bf460fe93e43fd308e3444bc79c3d88a4cb961dc8367ab6ad048867afc76d193bca99cf3a068864ed4a7df1dbf1d4c52238eced3e5e05644b4040fc2b3ccb8557b0e99fff6131305a0ea2b8061b90bd418db5bbdd2e92129f52d93f90531465e309c4caec5b85285822b6196398d36f16f511811b61bbda6461e80e29210cd303118bdcee8df6fa0505ffbe8642094fd2ba4dd458496fe3b459ac880bbf71877c713e969ccf5ed7efab8a84ebc07e3939901371ca427e1192e455a8f35a6a1d7ad09e1475dd1758b36fa631dab5d70e99316b23c4c43094188d360cd9c3457355904e07c00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000162074a7047f',
+      maxFeePerGas: Big {
+        s: 1,
+        e: 10,
+        c: [
+          6, 7, 6, 8, 1,
+          2, 6, 1, 6, 1,
+          8
+        ],
+        constructor: <ref *1> [Function: Big] {
+          DP: 20,
+          RM: 1,
+          NE: -7,
+          PE: 21,
+          strict: false,
+          roundDown: 0,
+          roundHalfUp: 1,
+          roundHalfEven: 2,
+          roundUp: 3,
+          Big: [Circular *1],
+          default: [Circular *1]
+        }
+      },
+      maxPriorityFeePerGas: Big {
+        s: 1,
+        e: 9,
+        c: [ 1, 5 ],
+        constructor: <ref *1> [Function: Big] {
+          DP: 20,
+          RM: 1,
+          NE: -7,
+          PE: 21,
+          strict: false,
+          roundDown: 0,
+          roundHalfUp: 1,
+          roundHalfEven: 2,
+          roundUp: 3,
+          Big: [Circular *1],
+          default: [Circular *1]
+        }
+      },
+      nonce: 129,
+      r: '0x59a7c15b12c18cd68d6c440963d959bff3e73831ffc938e75ecad07f7ee43fbc',
+      s: '0x1ebaf05f0d9273b16c2a7748b150a79d22533a8cd74552611cbe620fee3dcf1c',
+      to: '0x39B72d136ba3e4ceF35F48CD09587ffaB754DD8B',
+      transactionIndex: 29,
+      type: 2,
+      v: 0,
+      value: Big {
+        s: 1,
+        e: 0,
+        c: [ 0 ],
+        constructor: <ref *1> [Function: Big] {
+          DP: 20,
+          RM: 1,
+          NE: -7,
+          PE: 21,
+          strict: false,
+          roundDown: 0,
+          roundHalfUp: 1,
+          roundHalfEven: 2,
+          roundUp: 3,
+          Big: [Circular *1],
+          default: [Circular *1]
+        }
+      },
+      confirmations: 1210
+    }
 */
 ```
 
@@ -382,6 +609,19 @@ Any function on a contract. Returns are the same as `ethers.js`, except that ins
 <br/>
 <br/>
 
+![Screen Shot 2022-01-12 at 10 25 29 AM](https://user-images.githubusercontent.com/3408480/149190699-9bc15719-9382-46af-a77b-45e138f37643.png)
+
+![Screen Shot 2022-01-12 at 10 24 57 AM](https://user-images.githubusercontent.com/3408480/149190691-ed2913b9-8c14-4a8e-b5f8-0895fbac279b.png)
+
+## More Info
+
+🧪 This repo is under active development. The API is less-fully featured than `web3` and `ethers`. More functions added often!
+
+![](https://badgen.net/bundlephobia/minzip/essential-eth) ![](https://badgen.net/bundlephobia/tree-shaking/essential-eth) ![](https://img.shields.io/npm/v/essential-eth) ![](https://badgen.net/bundlephobia/dependency-count/essential-eth)
+
+👨🏻‍💻 Breaking changes will exist between minor versions until `1.0.0` (Versions go `major.minor.patch`)
+
+<br/>
+
 - [📓 View full docs](https://essential-eth.vercel.app)
 - [📓 View changelog (by looking at releases diff)](https://github.com/dawsbot/essential-eth/releases)
-- [📓 View docs for an older version](https://essential-eth.vercel.app/versions)