{"_id":"@0xhamachi/ethereum-events","_rev":"1-383192031c8bef17138941be6f6d7aa3","name":"@0xhamachi/ethereum-events","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@0xhamachi/ethereum-events","version":"0.1.0","description":"Efficient and reliable event listener for Ethereum.","main":"index.js","scripts":{"test":"mocha --recursive --exit","coverage":"nyc --all npm test","coveralls":"nyc npm test && nyc report --reporter=text-lcov | coveralls","lint":"eslint --ignore-path .gitignore .","lint:fix":"eslint --ignore-path .gitignore . --fix"},"repository":{"type":"git","url":"git+https://github.com/0xhamachi/ethereum-events.git"},"keywords":["ethereum","events","listener","solidity","logs","contracts","web3"],"author":{"name":"0xhamachi"},"license":"MIT","bugs":{"url":"https://github.com/0xhamachi/ethereum-events/issues"},"homepage":"https://github.com/0xhamachi/ethereum-events#readme","dependencies":{"eth-log-parser":"^0.1.0","p-limit":"^3.0.1","safe-memory-cache":"^2.0.0"},"devDependencies":{"chai":"^4.2.0","chai-as-promised":"^7.1.1","coveralls":"^3.1.0","eslint":"^7.2.0","mocha":"^8.0.1","nyc":"^15.1.0","sinon":"^9.0.2"},"gitHead":"8954f5f8b752ec7479a218bbec956693da8919ed","_id":"@0xhamachi/ethereum-events@0.1.0","_nodeVersion":"17.8.0","_npmVersion":"8.5.5","dist":{"integrity":"sha512-CEY+zJS5CMet8kJ/hjLHTRKMXZra6E0WAm4CvCbkFNAidVHQjckLD2AoQuTBcNIxVxsuChL6MSGH0+tbJY1OSA==","shasum":"109a2af17a7c088d01f4426895df6b68f29167c9","tarball":"https://registry.npmjs.org/@0xhamachi/ethereum-events/-/ethereum-events-0.1.0.tgz","fileCount":20,"unpackedSize":47111,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFCqLMMEH5hCJDzmN2uJZ3S0Zjr5A7F1gIxKvGyME+7VAiBGdDSaT5kge8klA86z0ujxj8saQTECQcAVlDVATFkZbQ=="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJiSYhrACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmpG1g//TiLg128c58wqmvwq3FehD4iloURFNCEtw4GX5Steh222TPKo\r\nqhTeOOAfNmNXCbPfC78Q4NRF5V0OKXeKRodO+RjIjOW+JD9fRihtrOuREJYI\r\nhQLhH782nE+wkNnWC6sxbnKpkbYGAGJOAhLHSSAY2zPpymEnoBDrwQcvS97Y\r\nvb28wtVpnh5Ffy25PZvRmDDecnQ5elGX0onCqJ5M6tARSbhAfRjm8+XrYEcr\r\nXq2TZkba1NmCF6CGbPbYyUfw9byddToDbA4deGJoAOn4je4xkmz4OaTj25MB\r\nvWjh/hSTHhTqDsYTiy5JXEig7UcYp8Z0wxQadTMlVv53bNWcpErRPovteLI/\r\nkFXrZB3l2XTy39O9E6aB0MjMoFSAXG2ul1dXiNMz5V3ZVkbP/ftmptyYQM4Y\r\ntyfh+TB4bjo1IFv7sksyeS4ErWU9+dFihJ+bOr+rLn6/FGTmEMwQKZfHpZNu\r\nBkwEqiJX/134z3GyBnXXv2h9yEmMwIlh+eXgDOmZ9CVaDGFNmbBFL7GLn9UC\r\nFWUz2Dzyi5Ts0EOPTzRkJ46nW03dAjyS9MD1exKcBK8lpueaD6f8PbR2dEhf\r\nOGbP6UaPz4vDZy/1gHBOLIvGytwUPpGuKV6+qFAZTwHXxVZLiRaml4zV6cPS\r\nXXzX7s5GkhZuycTpTSGbMXLBk9jMSwRivww=\r\n=PqY3\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"0xhamachi","email":"0x68616d61636869@protonmail.com"},"directories":{},"maintainers":[{"name":"0xhamachi","email":"0x68616d61636869@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/ethereum-events_0.1.0_1648986218847_0.9323098948626827"},"_hasShrinkwrap":false},"0.1.1":{"name":"@0xhamachi/ethereum-events","version":"0.1.1","description":"Efficient and reliable event listener for Ethereum.","main":"index.js","scripts":{"test":"mocha --recursive --exit","coverage":"nyc --all npm test","coveralls":"nyc npm test && nyc report --reporter=text-lcov | coveralls","lint":"eslint --ignore-path .gitignore .","lint:fix":"eslint --ignore-path .gitignore . --fix"},"repository":{"type":"git","url":"git+https://github.com/0xhamachi/ethereum-events.git"},"keywords":["ethereum","events","listener","solidity","logs","contracts","web3"],"author":{"name":"0xhamachi"},"license":"MIT","bugs":{"url":"https://github.com/0xhamachi/ethereum-events/issues"},"homepage":"https://github.com/0xhamachi/ethereum-events#readme","dependencies":{"eth-log-parser":"^0.1.0","p-limit":"^3.0.1","safe-memory-cache":"^2.0.0"},"devDependencies":{"chai":"^4.2.0","chai-as-promised":"^7.1.1","coveralls":"^3.1.0","eslint":"^7.2.0","mocha":"^8.0.1","nyc":"^15.1.0","sinon":"^9.0.2"},"gitHead":"ba9dbc9918e4f725b44c26682fef030cba7515cc","_id":"@0xhamachi/ethereum-events@0.1.1","_nodeVersion":"17.8.0","_npmVersion":"8.5.5","dist":{"integrity":"sha512-LZjEqFXVbJHZfsb0tRO0fiXZ3neIv2fIueIUQd1UGvJY+D8C8B5eNAz4a74bp1olTR4r+N/BvWzz4GEx5Kijew==","shasum":"f6e0337bd2f431ef53f4033b09fe6b2c8a25a564","tarball":"https://registry.npmjs.org/@0xhamachi/ethereum-events/-/ethereum-events-0.1.1.tgz","fileCount":20,"unpackedSize":47185,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIFXWWcb+EvF1TG91bDoocQW4GdnjPpxMQQpchDBTWnd4AiBq18746ySNwPMiwMpbrGZ9sCvvc9r8TaFMQaefLHDLJg=="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJjRcGmACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmp6+Q/+Jfs8OREAP0gBuO2Fc/V6v1A9BY+aOyRagxq6j5XdJ/bdcOQZ\r\nsKV7h7mDEne2UQ46Kpx6mbhbW2DzTLAqnwXXoWcavXAiEd4aIYHRVA0oVKSm\r\nK53ZluCTppC5zlP/dILoqTWyONOenE2IrR8dvi0bijQJ2eAOPE53ues9HPiz\r\nY7eJ7WyF0U6deFsuxhQAoF9VnD7uulxPMZgvYDZ+GSe94IuvpYP41DLFM2wi\r\n/jAnjVORAqM3l4TPYKdRJv+Z7TDA1HTs7Y6IdhnYyhIWIC/fb+gbXE+CyMez\r\nONAz8lPz5mwQ4S+ax3F+OJieWEIgnTY0SVD3DKPxfLwsEeY7OJgl6kvS5yWO\r\nBz71mV4Eo+JxsZL9Ul8HzRiOrnGoOzRFMCjwgvG7SNYOjRxbCLvJs+R5BtRP\r\nQwdcH8n8L95XEH3cc5cWPbWi3jvLV6ysZDdSOGJGk4nZ5vNPzRtjrE/ShWBV\r\nZwDJbMeSkYX3OC3Ij1dNqJip0A3zZGYSluh/9v/trs9QFSzDCEf15l+p38F0\r\nMo9VjwLIL8OpJ+71BlXTITcOFGcMqR9zpQdNQRHucgQz4FDntM94+ZuQneKn\r\nVVIqpx4tUIv7wVmIja76LDWyVEOrEPUlbMDkt8lidan935kEvLAeeaS+JVCQ\r\nrwIAreDEzXVM25/nTSnddQcnN12hHKPGzaI=\r\n=CeHp\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"0xhamachi","email":"0x68616d61636869@protonmail.com"},"directories":{},"maintainers":[{"name":"0xhamachi","email":"0x68616d61636869@protonmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/ethereum-events_0.1.1_1665515942453_0.7485840056814326"},"_hasShrinkwrap":false}},"time":{"created":"2022-04-03T11:43:38.782Z","0.1.0":"2022-04-03T11:43:39.005Z","modified":"2022-10-11T19:19:02.753Z","0.1.1":"2022-10-11T19:19:02.688Z"},"maintainers":[{"name":"0xhamachi","email":"0x68616d61636869@protonmail.com"}],"description":"Efficient and reliable event listener for Ethereum.","homepage":"https://github.com/0xhamachi/ethereum-events#readme","keywords":["ethereum","events","listener","solidity","logs","contracts","web3"],"repository":{"type":"git","url":"git+https://github.com/0xhamachi/ethereum-events.git"},"author":{"name":"0xhamachi"},"bugs":{"url":"https://github.com/0xhamachi/ethereum-events/issues"},"license":"MIT","readme":"# Ethereum Events\n\n[![CircleCI][circleci-image]][circleci-url]\n[![NPM Version][npm-image]][npm-url]\n[![Coverage Status][coveralls-image]][coveralls-url]\n[![License][license-image]][license-url]\n\nEfficient and reliable event listener for Ethereum.\n\nReceive real-time events from your contracts with minimal effort.\n\n## Changes\n\n- Added `removeAllListeners` functionality ([reference](https://nodejs.org/docs/latest/api/events.html#emitterremovealllistenerseventname))\n\n## Motivation\n\nEthereum, and blockchains in general, can be quite challenging for new developers to approach. Most of the difficulty resides in understanding the many dynamics that can occur (e.g. finality, reorgs) and how to deal with them to provide quality UX.\n\nA lot of Ethereum based dApps heavily depend on events fired by their smart contracts.\nThis package is meant to simplify the process of listening for these real-time events in a reliable yet efficient way, keeping away blockchain complexity as much as possible.\n\n\n## How it works\n\nEthereumEvents continuously polls the Ethereum blockchain for new blocks. As soon as a new block is detected, the events contained inside it are immediately delivered for processing. \n\nSince, in the blockchain environment, finality is probabilistic and increases with the number of subsequent blocks mined, blocks are delivered using two different channels: `confirmed` and `unconfirmed`.\n\nUnconfirmed blocks are newer blocks that can be subject to reorgs, so the events contained inside them may still change.\n\nConfirmed blocks, on the other hand, are older blocks that have reached a certain number of confirmations. It is relatively safe to assume that the events contained inside them are final and will not change.\n\nFor the vast majority of use cases, the default value of 12 confirmations is considered safe but it can be adjusted to fit every need.\n\n\n## Requirements\n\n* Web3 (1.2.0 or higher)\n\n\n## Installation\n\n```\nnpm install ethereum-events\n```\n\n\n## Usage\n\n### Setup and instantiate\n\n```js\nconst Web3 = require('web3');\nconst EthereumEvents = require('ethereum-events');\n\nconst ERC20_ABI = /* ABI for ERC20 token contract */;\nconst WEB3_PROVIDER = /* Your web3 provider (e.g. geth, Infura) */;\n\nconst contracts = [\n  {\n    name: 'Token',\n    address: '0xefE1e4e13F9ED8399eE8e258b3a1717b7D15f054',\n    abi: ERC20_ABI,\n    events: ['Transfer'] // optional event filter (default: all events)\n  } \n];\n\nconst options = {\n  pollInterval: 13000, // period between polls in milliseconds (default: 13000)\n  confirmations: 12,   // n° of confirmation blocks (default: 12)\n  chunkSize: 10000,    // n° of blocks to fetch at a time (default: 10000)\n  concurrency: 10,     // maximum n° of concurrent web3 requests (default: 10)\n  backoff: 1000        // retry backoff in milliseconds (default: 1000)\n};\n\nconst web3 = new Web3(WEB3_PROVIDER);\n\nconst ethereumEvents = new EthereumEvents(web3, contracts, options);\n```\n\n### Register listeners\n\n```js\nethereumEvents.on('block.confirmed', (blockNumber, events, done) => {\n\n  // Events contained in 'confirmed' blocks are considered final,\n  // hence the callback is fired only once for each blockNumber.\n  // Blocks are delivered in sequential order and one at a time so that none is skipped\n  // and you know for sure that every block up to the latest one received was processed.\n  \n  // Call 'done()' after processing the events in order to receive the next block. \n  // If an error occurs, calling 'done(err)' will retry to deliver the same block\n  // without skipping it.\n\n});\n\nethereumEvents.on('block.unconfirmed', (blockNumber, events, done) => {\n  \n  // Events contained in 'unconfirmed' blocks are NOT considered final\n  // and may be subject to change, hence the callback may be fired multiple times\n  // for the same blockNumber if the events contained inside that block change.\n  // Blocks are received one at a time but, due to reorgs, the order is not guaranteed.\n  \n  // Call 'done()' after processing the events in order to receive the next block. \n  // If an error occurs, calling 'done(err)' will retry to deliver the same block\n  // without skipping it.\n  \n});\n\nethereumEvents.on('error', err => {\n\n  // An error occured while fetching new blocks/events.\n  // A retry will be attempted after backoff interval.\n\n});\n\n```\n\n### Start listening\n\n```js\nconst startBlock = 6596988;\n\nethereumEvents.start(startBlock); // startBlock defaults to 'latest' when omitted\n\nethereumEvents.isRunning() // true\n\n// Stop listening for events\nethereumEvents.stop();\n```\n\n\n## Event Format\n\n```jsonc\n{\n  \"name\": \"Transfer\",\n  \"contract\": \"Token\",\n  \"timestamp\": 1591110290,\n  \"blockHash\": \"0xde42b82c4e28122218d79f8491b05587608a8c9bb87c0d0df9be9fb9ae6f7e13\",\n  \"blockNumber\": 6596988,\n  \"transactionHash\": \"0x686943cee4035375b25209a2972535c93eefb688fad42d72e518c452387c69c9\",\n  \"transactionIndex\": 10,\n  \"from\": \"0x5B848132d3a0111d4daB7060b6051961013C71c7\",  // sender of the transaction\n  \"to\": \"0xefE1e4e13F9ED8399eE8e258b3a1717b7D15f054\",    // receiver of the transaction\n  \"logIndex\": 11,\n  \"values\": {\n    \"from\": \"0x343c6A169D973bBF33A8F1535754A4745a3BD9C1\",\n    \"to\": \"0x78a3339aD6A565B4136077C8878970D7f1B66021\",\n    \"value\": \"100000000000000000000\"\n  }\n}\n```\n\n\n## Notes\n\nThe `chunkSize` option lets you customize how many blocks to query for events at a time. This is useful when the start block is far behind the current latest block and many blocks have to be fetched to get up to date.\\\nHaving a higher *chunkSize* is more performant but it may cause a failure in the calls to your provider if too many events are retrieved in the same request so the optimal value heavily depends on how many events your contracts emit.\n\nThe `concurrency` option lets you customize how many concurrent requests can be made to your web3 provider so that you can avoid being rate limited.\n\n\n[circleci-image]: https://circleci.com/gh/AleG94/ethereum-events.svg?style=svg\n[circleci-url]: https://circleci.com/gh/AleG94/ethereum-events\n[coveralls-image]: https://coveralls.io/repos/github/AleG94/ethereum-events/badge.svg?branch=master\n[coveralls-url]: https://coveralls.io/github/AleG94/ethereum-events?branch=master\n[npm-image]: https://img.shields.io/npm/v/ethereum-events.svg\n[npm-url]: https://npmjs.org/package/ethereum-events\n[license-image]: https://img.shields.io/npm/l/ethereum-events.svg\n[license-url]: https://github.com/AleG94/ethereum-events/blob/master/LICENSE","readmeFilename":"README.md"}