{"id":27608132,"url":"https://github.com/merklejerk/flex-ether","last_synced_at":"2025-04-22T22:23:26.801Z","repository":{"id":33387488,"uuid":"142085952","full_name":"merklejerk/flex-ether","owner":"merklejerk","description":"A modern, flexible library for sending ethereum transactions.","archived":false,"fork":false,"pushed_at":"2023-03-04T03:48:24.000Z","size":1502,"stargazers_count":22,"open_issues_count":9,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-16T18:19:05.368Z","etag":null,"topics":["async","await","easy","ens","es2017","ether","ethereum","library","private-key","promise","self-signed","send","simple","transfer","wallet","web3"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/merklejerk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-24T01:03:18.000Z","updated_at":"2024-04-11T06:27:35.000Z","dependencies_parsed_at":"2024-06-19T02:36:39.700Z","dependency_job_id":"d4063539-9c5b-47a0-ad87-dc6adc23acfa","html_url":"https://github.com/merklejerk/flex-ether","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merklejerk%2Fflex-ether","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merklejerk%2Fflex-ether/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merklejerk%2Fflex-ether/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merklejerk%2Fflex-ether/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/merklejerk","download_url":"https://codeload.github.com/merklejerk/flex-ether/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249840732,"owners_count":21332933,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","await","easy","ens","es2017","ether","ethereum","library","private-key","promise","self-signed","send","simple","transfer","wallet","web3"],"created_at":"2025-04-22T22:23:26.133Z","updated_at":"2025-04-22T22:23:26.774Z","avatar_url":"https://github.com/merklejerk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![build status](https://travis-ci.org/merklejerk/flex-ether.svg?branch=master)](https://travis-ci.org/merklejerk/flex-ether)\n[![npm package](https://badge.fury.io/js/flex-ether.svg)](https://www.npmjs.com/package/flex-ether)\n\n# flex-ether\nA flexible Ethereum library for sending ethereum transactions that:\n\n- Requires minimal to *no* configuration to get going on all networks (no provider necessary).\n- Can sign and send transactions from arbitrary wallets (private keys).\n- Provides separate promises for transaction hashes, receipts, and confirmations.\n- Automatically calculates gas and gas price for transactions in a configurable manner.\n- Automatically resolves ENS addresses across all inputs.\n\n## Installation\n```bash\nnpm install flex-ether\n# or\nyarn install flex-ether\n```\n\n## Preview\n\n```js\nconst FlexEther = require('flex-ether');\n// A self-signing wallet key for transactions.\nconst PRIVATE_KEY = '0xb3734ec890893585330c71ece72afb05058192b6be47bee2b99714e6bb5696ab';\n\n// Create instance on the mainnet.\nlet eth = new FlexEther();\n// Send 100 wei from a self-signed wallet to an ENS address.\nlet tx = eth.transfer('ethereum.eth', '100', {key: PRIVATE_KEY});\n// Wait for the transaction hash.\nlet transactionHash = await tx.txId;\n// Wait for the receipt.\nreceipt = await tx.receipt;\n// Wait for the receipt after 3 confirmations.\nreceipt = await tx.confirmed(3);\n// Get the balance of an address at a certain block.\nlet balance = await eth.getBalance('0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', 412045);\n// Estimate gas for a transaction, from a self-signed wallet.\nlet gas = eth.estimateGas('0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', '100',\n   {key: PRIVATE_KEY});\n```\n\n## User Guide\n- [Creating an instance](creating-an-instance)\n- [Sending ether](#sending-ether)\n- [Transaction promises](#transaction-promises)\n- [Getting balances](#getting-balances)\n- [Estimating gas](#estimating-gas)\n- [ENS addresses](#ens-addresses)\n- [Instance Properties](#instance-properties)\n- [Other Methods](#other-methods)\n\n### Creating an instance\nBy default, the instance will create an [Infura](https://infura.io) provider to\ntalk to the main network. You can modify this behavior with the options\n`network`, `infuraKey`, `provider`, or `providerURI`.\n\n##### Full options\n```js\neth = new FlexEther(\n   // Options object. May be omitted.\n   {\n      // Network to use with Infura provider.\n      // May be 'main', 'ropsten', 'rinkeby', or 'kovan'.\n      // Defaults to 'main'\n      network: String,\n      // Infura Project ID, if not using a custom provider.\n      infuraKey: String,\n      // Whether to use a websocket connection instead of an HTTPS connection\n      // when using Infura.\n      ws: boolean,\n      // Connect to an existing provider at a URI\n      // (e.g., http://localhost:8545 or https://mainnet.infura.io/v3/PROJECT_ID).\n      // The 'net' option is required is using an IPC path.\n      providerURI: String,\n      // net instance, from require('net'), if using IPC path in providerURI\n      net: Object,\n      // Use a custom provider instance (e.g., web3.currentProvider for metamask).\n      provider: Object,\n      // Clamp transaction gas prices to this amount (in wei).\n      // Defaults to 250 gwei.\n      maxGasPrice: string,\n      // Fractional bonus to apply to gas price when making transactions.\n      // Affects gasPrice, maxPriorityFeePerGas, and maxFeePerGas.\n      // 0.01 = +1%. May be negative to under-price.\n      // Defaults to -0.005.\n      // Can be overridden in send/transfer calls.\n      gasPriceBonus: Number,\n      // Fractional bonus to apply to gas limit estimates when making transactions.\n      // 0.01 = +1%. May be negative, but probably not a good idea.\n      // Defaults to 0.66.\n      // Can be overridden in send/transfer calls.\n      gasBonus: Number,\n      // ENS options.\n      ens: {\n          // Minimum number of seconds time to keep a resolved ENS name in cache.\n          // Defaults to one hour.\n          minTTL: Number,\n          // Maximum number of seconds time to keep a resolved ENS name in cache.\n          // Defaults to infinity.\n          maxTTL: Number,\n      }\n   });\n```\n\n### Sending ether\n\nEther can be sent with the `transfer()` or the lower-level `send()`/`call()` methods.\n\nBy default, transactions will be signed by the wallet associated with\nthe first account given by the provider. You can override the\ncaller by either passing the `from` or `key` option. The `from` option will\nlet the provider sign the transaction from an unlocked wallet, as usual.\nBut, the `key` option will *self-sign* the transaction with the private key\nprovided, allowing you to transact from any wallet you have the private keys\nto.\n\nTransactions return a [Transaction Promise Object](#transaction-promises), which\nallow you to easily wait on transaction hashes,\n[receipts](https://web3js.readthedocs.io/en/1.0/web3-eth.html#eth-gettransactionreceipt-return),\nand confirmations.\n\n##### Examples\n```js\nconst FlexEther = require('flex-ether');\n// A self-signing wallet key for transactions.\nconst PRIVATE_KEY = '0xb3734ec890893585330c71ece72afb05058192b6be47bee2b99714e6bb5696ab';\nconst eth = new FlexEther();\n\n// Send 100 wei to an ENS address and wait for the receipt.\nlet receipt = await eth.transfer('ethereum.eth', '100');\n/* Result: \u003cReceipt Object\u003e {\n   transactionHash: '0x9eb3f89f8581e6c6df294344b538d44e265c226ae6e8ce6210df497cf2b54bd3',\n   blockNumber: 3616104,\n   gasUsed: 21000,\n   ... etc.\n}*/\n// Send 100 wei to an address and wait for the transaction hash.\nlet txId = await eth.transfer(\n   '0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', '100').txId;\n// Send 100 wei to an address and wait for the receipt after 3 confirmations.\nreceipt = await eth.transfer(\n   '0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', '100').confirmed(3);\n// Send 100 wei from a wallet managed by the provider and wait for the receipt\nreceipt = await eth.transfer(\n   '0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', '100',\n   {from: '0x005B68A967D39c497074127871297b6728a1cfEd'});\n// Send 100 wei from a wallet defined by a private key and wait for the receipt\nreceipt = await eth.transfer(\n   '0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', '100', {key: PRIVATE_KEY});\n// Same as above but with send(). transfer() is actually just a wrapper for send()\nreceipt = await eth.send(\n   '0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', {value: '100', key: PRIVATE_KEY});\n// Same as above but without actually writing to the blockchain and retrieving any\n// output data.\n   receipt = await eth.send(\n      '0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', {value: '100', key: PRIVATE_KEY});\n```\n\n##### Full options\n```js\n// Full method options.\nawait eth.transfer(\n   // Recipient address. May be an ENS address.\n   to: String,\n   // Amount of ether to send, in weis.\n   // Can be a base-10 string or hex-encoded number.\n   amount: String,\n   // Options.\n   {\n      // Address of wallet that will sign the transaction. May be an ENS address.\n      // Must be unlocked by the provider.\n      // Defaults to eth.getDefaultAccount().\n      from: String,\n      // Hex-encoded string private key.\n      // Signs the transaction with this private key and sends it from the address\n      // associated with it. Overrides 'from' option.\n      key: String,\n      // Any extra hex-encoded data (usually contract calldata) to attach to the transaction.\n      data: String,\n      // The block number at which to perform the `call()` or `estimateGas()` at.\n      // Only used by `call()` and `estimateGas()`. Can be a block number, a\n      // relative offset from the highest block number, or a directive like\n      // 'latest' or 'pending'.\n      block: String,\n      // Legacy gas price to use, as a hex or base-10 string, in wei.\n      // Is overridden by `maxFeePerGas` and `maxPriorityFeePerGas`.\n      // If not specified, calculated from network gas price and bonus.\n      gasPrice: String,\n      // Maximum ETH per gas unit to spend on fees (basefee + priority tip),\n      // as a hex or base-10 string, in wei.\n      // If not specified, will be:\n      // `baseFee * gasPriceBonus + maxPriorityFeePerGas`\n      maxFeePerGas: String,\n      // Maximum ETH per gas unit to spend on priority tip for the miner,\n      // as a hex or base-10 string, in wei.\n      // If not specified, will be:\n      // `maxPriorityFeePerGas * gasPriceBonus`\n      maxPriorityFeePerGas: String,\n      // Execution gas limit.\n      // If not specified, it will be estimated with bonus.\n      gas: Number,\n      // Bonus to apply to gas price calculations.\n      // Should be a positive or negative Number, where 0.01 = +1%.\n      // If omitted, `eth.gasPriceBonus` will be used.\n      gasPriceBonus: undefined,\n      // Bonus to apply to gas limit calculations.\n      // Should be a positive or negative Number, where 0.01 = +1%.\n      // If omitted, `eth.gasBonus` will be used.\n      gasBonus: undefined\n   });\n```\n\n### Transaction promises\n`transfer()` and `send()` both return a Promise object that resolves\nto the\n[transaction receipt](https://web3js.readthedocs.io/en/1.0/web3-eth.html#eth-gettransactionreceipt-return),\nonce the transaction has been mined.\n\nThis Promise object also has the following properties:\n- `txId`: a promise that resolves to the transaction hash when the transaction is\nposted to the blockchain. This ususally comes much sooner than the receipt.\n- `receipt`: a promise that resolves to the transaction receipt when the\ntransaction has been mined. Same as waiting on the parent object itself.\n- `confirmed(count=1)` a function that returns a promise that resolves to the\ntransaction receipt after the transaction has been mined and `count` number of\nconfirmations have been seen, up to a maximum of 12 confirmations.\n\n##### Example\n```js\nconst FlexEther = require('flex-ether');\nconst eth = new FlexEther();\n\n// Send 100 wei to an address and wait for the receipt.\nlet receipt = await eth.transfer(\n   '0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', '100');\n// Send 100 wei to an address and get the promise object.\nlet tx = eth.transfer(\n   '0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', '100');\n// Wait on the transaction hash.\nlet transactionHash = await tx.txId;\n// Wait on the receipt. Equivalent to `await tx`\nreceipt = await tx.receipt;\n// Wait on the receipt after 3 confirmations. Equivalent to `await tx`\nreceipt = await tx.confirmed(3);\n```\n\n### Getting balances\nThe `getBalance()` method queries the balance of an address.\n\nYou can also pass the block number at which to evaluate the balance. These\nnumbers can either be explicit block numbers or negative offsets from the last\nblock number, where `-1` is the last block, `-2` is the second to last block,\nand so on.\n\n##### Examples\n```js\nconst FlexEther = require('flex-ether');\nconst eth = new FlexEther();\n\n// Get the balance of an address at the current block.\nlet bal = await eth.getBalance('0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1');\n// Get the balance of an address at a specific block.\nbal = await eth.getBalance('0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1', 310319);\n// Get the balance of an ENS address at the second to last block.\nbal = await eth.getBalance('ethereum.eth', -2);\n\n```\n\n### Estimating gas\nSending ether from wallet to wallet generally costs exactly `21000` gas. However,\nsending ether to a contract may actually cost more, as it might trigger the\nexecution of code. By default, the library will automatically compute and\nallocate the gas needed before sending a transaction.\n\nYou can get the gas explicitly by calling `estimateGas()` with the same\nparameters you would pass to `call()`.\n\n##### Examples\n```js\nconst FlexEther = require('flex-ether');\n// A self-signing wallet key for transactions.\nconst PRIVATE_KEY = '0xb3734ec890893585330c71ece72afb05058192b6be47bee2b99714e6bb5696ab';\nconst eth = new FlexEther();\n\n// Get the gas consumed by sending 100 wei to an address from the default account.\nlet gas = await eth.estimateGas('0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1',\n   {value: '100'});\n// Get the gas consumed by sending 100 wei to an address from a wallet defined by\n// a private key.\nlet gas = await eth.estimateGas('0xf6fb5b73987d6d9a139e23bab97be6fc89e0dcd1',\n   {value: '100', key: PRIVATE_KEY});\n```\n\n### ENS addresses\nAnywhere you can pass an address, you can instead pass an\n[ENS address](http://docs.ens.domains/en/latest/introduction.html), such as\n`'thisismyensaddress.eth'`. You can also call the `resolveAddress()` method\nto resolve an address explicitly. If an ENS address cannot be resolved, an\nexception will be raised (the promise will fail).\n\nENS is only available on the main, ropsten, and rinkeby networks.\nThe ENS address will also have to be set up with the ENS contract on the\nrespective network to properly resolve.\n\n### Instance Properties\nA contract instance exposes a few properties, most of which you are free to\nchange. Many of these can also be overridden in individual call options.\n\n- `gasBonus (Number)` Gas limit estimate bonus for transactions, where `0.01 = +1%`. May be negative.\n- `gasPriceBonus (Number)` Gas price bonus for transactions, where `0.01 = +1%`. May be negative.\n\n### Other Methods\n- `async getTransactionCount(addr)` Get the nonce for an account.\n- `async getTransaction(txHash)` Get the details of a submitted transaction.\n- `async getTransactionReceipt(txHash)` Get the receipt for a mined transaction.\n- `async getGasPrice()` Get the legacy suggested gas price.\n- `async getBaseFee()` Get the current base block fee (EIP-1559 networks only).\n- `async getMaxPriorityFeePerGas()` Get the suggested max priority fee (EIP-1559 networks only).\n- `async resolveBlockDirective(blockNum)` Resolve a block directive (e.g., `41204102` or `-2`) to a block number.\n- `async getChainId()` Get the chain ID of the connected network.\n- `async resolveAddress(addr, block='latest')` Resolve an ENS address. If a regular address is passed, the checksummed version will be returned.\n- `async getBlockNumber()` Get the current block number.\n- `async getDefaultAccount()` Get the default account, set by the provider.\n- `async getCode(addr, block='latest')` Get the code bytes at `addr`.\n- `async getPastLogs(filter)` Get past logs using `filter`, as defined by a filter object similar to the [JSONRPC spec](https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getlogs).\n\n### Module Properties\nThe following module properties affect gas calculations for all instances:\n\n- `MAX_GAS_PRICE` Maximum gas price for transactions. Defaults to `256` gwei.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerklejerk%2Fflex-ether","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmerklejerk%2Fflex-ether","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerklejerk%2Fflex-ether/lists"}