{"id":13792336,"url":"https://github.com/eventeum/eventeum","last_synced_at":"2025-05-12T14:31:48.094Z","repository":{"id":37259657,"uuid":"126844782","full_name":"eventeum/eventeum","owner":"eventeum","description":"A resilient Ethereum event listener that bridges your smart contract events and backend microservices","archived":false,"fork":false,"pushed_at":"2023-04-29T11:00:14.000Z","size":1152,"stargazers_count":496,"open_issues_count":36,"forks_count":145,"subscribers_count":27,"default_branch":"master","last_synced_at":"2024-05-23T07:52:47.522Z","etag":null,"topics":["blockchain","ethereum","ethereum-blockchain","event-broadcasting","event-driven","event-listener","kafka","smart-contracts"],"latest_commit_sha":null,"homepage":"","language":"Java","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/eventeum.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}},"created_at":"2018-03-26T14:52:18.000Z","updated_at":"2024-05-23T03:59:09.000Z","dependencies_parsed_at":"2022-07-12T05:00:24.948Z","dependency_job_id":"720dc15b-b489-4358-816c-136840a8b7ac","html_url":"https://github.com/eventeum/eventeum","commit_stats":null,"previous_names":["consensys/eventeum"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eventeum%2Feventeum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eventeum%2Feventeum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eventeum%2Feventeum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eventeum%2Feventeum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eventeum","download_url":"https://codeload.github.com/eventeum/eventeum/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253754967,"owners_count":21958934,"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":["blockchain","ethereum","ethereum-blockchain","event-broadcasting","event-driven","event-listener","kafka","smart-contracts"],"created_at":"2024-08-03T22:01:11.134Z","updated_at":"2025-05-12T14:31:47.441Z","avatar_url":"https://github.com/eventeum.png","language":"Java","funding_links":[],"categories":["Roadmap"],"sub_categories":[],"readme":"# Eventeum\nAn Ethereum event listener that bridges your smart contract events and backend microservices. Eventeum listens for specified event emissions from the Ethereum network, and broadcasts these events into your middleware layer. This provides a distinct separation of concerns and means that your microservices do not have to subscribe to events directly to an Ethereum node.\n\n[![Gitter](https://badges.gitter.im/eventeum/community.svg)](https://gitter.im/eventeum/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n\n**Master**\n\n[![CircleCI](https://circleci.com/gh/ConsenSys/eventeum/tree/master.svg?style=svg)](https://circleci.com/gh/ConsenSys/eventeum/tree/master)\n\n**Development**\n\n[![CircleCI](https://circleci.com/gh/ConsenSys/eventeum/tree/development.svg?style=svg)](https://circleci.com/gh/ConsenSys/eventeum/tree/development)\n\n## Features\n* Dynamically Configurable - Eventeum exposes a REST api so that smart contract events can be dynamically subscribed / unsubscribed.\n\n* Highly Available - Eventeum instances communicate with each other to ensure that every instance is subscribed to the same collection of smart contract events.\n\n* Resilient - Node failures are detected and event subscriptions will continue from the failure block once the node comes back online.\n\n* Fork Tolerance - Eventeum can be configured to wait a certain amount of blocks before an event is considered 'Confirmed'.  If a fork occurs during this time, a message is broadcast to the network, allowing your services to react to the forked/removed event.\n\n## Supported Broadcast Mechanisms\n* Kafka\n* HTTP Post\n* [RabbitMQ](https://www.rabbitmq.com/)\n* [Pulsar](https://pulsar.apache.org)\n\n\nFor RabbitMQ, you can configure the following extra values\n\n* rabbitmq.blockNotification. true|false\n* rabbitmq.routingKey.contractEvents\n* rabbitmq.routingKey.blockEvents\n* rabbitmq.routingKey.transactionEvents\n\n## Eventeum Tutorials\n- [Listening to Ethereum Events](https://kauri.io/article/90dc8d911f1c43008c7d0dfa20bde298/listening-to-ethereum-events-with-eventeum)\n- [Listening for Ethereum Transactions](https://kauri.io/article/3e31587c96a74d24b5cdd17952d983e9/v1/listening-for-ethereum-transactions-with-eventeum)\n- [Using Eventeum to Build a Java Smart Contract Data Cache](https://kauri.io/article/fe81ee9612eb4e5a9ab72790ef24283d/using-eventeum-to-build-a-java-smart-contract-data-cache)\n\n## Getting Started\nFollow the instructions below in order to run Eventeum on your local machine for development and testing purposes.\n\n### Prerequisites\n* Java 8\n* Maven\n* Docker (optional)\n\n### Build\n1. After checking out the code, navigate to the root directory\n```\n$ cd /path/to/eventeum/\n```\n\n2. Compile, test and package the project\n```\n$ mvn clean package\n```\n\n### Run\n\na. If you have a running instance of MongoDB, Kafka, Zookeeper and an Ethereum node:\n\n**Executable JAR:**\n\n```sh\n$ cd server\n$ export SPRING_DATA_MONGODB_HOST=\u003cmongodb-host:port\u003e\n$ export ETHEREUM_NODE_URL=http://\u003cnode-host:port\u003e\n$ export ZOOKEEPER_ADDRESS=\u003czookeeper-host:port\u003e\n$ export KAFKA_ADDRESSES=\u003ckafka-host:port\u003e\n$ export RABBIT_ADDRESSES=\u003crabbit-host:port\u003e\n\n$ java -jar target/eventeum-server.jar\n```\n\n**Docker:**\n\n```sh\n$ cd server\n$ docker build  . -t kauri/eventeum:latest\n\n$ export SPRING_DATA_MONGODB_HOST=\u003cmongodb-host:port\u003e\n$ export ETHEREUM_NODE_URL=http://\u003cnode-host:port\u003e\n$ export ZOOKEEPER_ADDRESS=\u003czookeeper-host:port\u003e\n$ export KAFKA_ADDRESSES=\u003ckafka-host:port\u003e\n$ export RABBIT_ADDRESSES=\u003crabbit-host:port\u003e\n\n$ docker run -p 8060:8060 kauri/eventeum\n```\n\nb. If you prefer build an all-in-one test environment with a parity dev node, use docker-compose:\n\n```sh\n$ cd server\n$ docker-compose -f docker-compose.yml build\n$ docker-compose -f docker-compose.yml up\n```\n\n## SQL Support\nEventeum now supports a SQL database as well as the default MongoDB.  To use a SQL database (only SQL Server has currently been tested but others should be supported with the correct config), set the `database.type` property to `SQL` and ensure you have all required additional properties in your properties file. See `config-examples/application-template-sqlserver.yml` for a sample SQLServer configuration.\n\n### Upgrading to 0.8.0\n\nWhen upgrading Eventeum to **0.8.0**, changes in the schema are required. In order to perform the migration follow these steps:\n\n1. Stop all Evnteum instances\n2. Backup your database\n3. Apply the [tools/potgres-upgrade-to-v0.8.0.sql](tools/postgres-upgrade-to-v0.8.0.sql) sql script. Note that this script is written for Postgres, syntax may differ if using other database system.\n4. Restart Eventeum instances\n\n\n## Configuring Nodes\nListening for events from multiple different nodes is supported in Eventeum, and these nodes can be configured in the properties file.\n\n```yaml\nethereum:\n  nodes:\n    - name: default\n      url: http://mainnet:8545\n    - name: sidechain\n      url: wss://sidechain/ws\n```\n\nIf an event does not specify a node, then it will be registered against the 'default' node.\n\nThat is the simplest node configuration, but there is other custom flags you can activate per node:\n\n\n- `maxIdleConnections`: Maximum number of connections to the node. (default: 5)\n- `keepAliveDuration`: Duration of the keep alive http in milliseconds (default: 10000)\n- `connectionTimeout`: Http connection timeout to the node in milliseconds (default: 5000)\n- `readTimeout`: Http read timeout to the node in milliseconds (default: 60000)\n- `addTransactionRevertReason`: Enables receiving the revert reason when a transaction fails.  (default: false)\n- `pollInterval`: Polling interval of the rpc request to the node (default: 10000)\n- `healthcheckInterval`: Polling interval of that evenreum will use to check if the node is active (default: 10000)\n- `numBlocksToWait`: Blocks to wait until we decide event is confirmed (default: 1). Overrides broadcaster config\n- `numBlocksToWaitBeforeInvalidating`:  Blocks to wait until we decide event is invalidated (default: 1).  Overrides broadcaster config\n- `numBlocksToWaitForMissingTx`: Blocks to wait until we decide tx is missing (default: 1)  Overrides broadcaster config\n\nThis will be an example with a complex configuration:\n\n```yaml\nethereum:\n  nodes:\n  - name: default\n    url: http://mainnet:8545\n    pollInterval: 1000\n    maxIdleConnections: 10\n    keepAliveDuration: 15000\n    connectionTimeout: 7000\n    readTimeout: 35000\n    healthcheckInterval: 3000\n    addTransactionRevertReason: true\n    numBlocksToWait: 1\n    numBlocksToWaitBeforeInvalidating: 1\n    numBlocksToWaitForMissingTx: 1\n  blockStrategy: POLL\n\n```\n\n## Registering Events\n\n### REST\nEventeum exposes a REST api that can be used to register events that should be subscribed to / broadcast.\n\n-   **URL:** `/api/rest/v1/event-filter`    \n-   **Method:** `POST`\n-   **Headers:**  \n\n| Key | Value |\n| -------- | -------- |\n| content-type | application/json |\n\n-   **URL Params:** `N/A`\n-   **Body:**\n\n```json\n{\n\t\"id\": \"event-identifier\",\n\t\"contractAddress\": \"0x1fbBeeE6eC2B7B095fE3c5A572551b1e260Af4d2\",\n\t\"eventSpecification\": {\n\t\t\"eventName\": \"TestEvent\",\n\t\t\"indexedParameterDefinitions\": [\n\t\t  {\"position\": 0, \"type\": \"UINT256\"},\n\t\t  {\"position\": 1, \"type\": \"ADDRESS\"}],\n\t\t\"nonIndexedParameterDefinitions\": [\n\t\t  {\"position\": 2, \"type\": \"BYTES32\"},\n\t\t  {\"position\": 3, \"type\": \"STRING\"}] },\n\t\"correlationIdStrategy\": {\n\t\t\"type\": \"NON_INDEXED_PARAMETER\",\n\t\t\"parameterIndex\": 0 }\n}\n```\n| Name | Type | Mandatory | Default | Description |\n| -------- | -------- | -------- | -------- | -------- |\n| id | String | no | Autogenerated | A unique identifier for the event. |\n| contractAddress | String | yes |  | The address of the smart contract that the address will be emitted from. |\n| eventSpecification | json | yes |  | The event specification |\n| correlationIdStrategy | json | no | null | Define a correlation id for the event (only used with the Kafka broadcaster).  See the advanced section for details. |\n\n**eventSpecification**:\n\n| Name | Type | Mandatory | Default | Description |\n| -------- | -------- | -------- | -------- | -------- |\n| eventName | String | yes | | The event name within the smart contract |\n| indexedParameterTypes | String array | no | null | The array of indexed parameter types for the event. |\n| nonIndexedParameterTypes | String array | no | null | The array of non-indexed parameter types for the event. |\n\n**parameterDefinition**:\n\n| Name | Type | Mandatory | Default | Description |\n| -------- | -------- | -------- | -------- | -------- |\n| position | Number | yes | | The zero indexed position of the parameter within the event specification |\n| type | String | yes | | The type of the event parameter. |\n\nCurrently supported parameter types: `UINT8-256`, `INT8-256`, `ADDRESS`, `BYTES1-32`, `STRING`, `BOOL`.\n\nDynamically sized arrays are also supported by suffixing the type with `[]`, e.g. `UINT256[]`.\n\n**correlationIdStrategy**:\n\n| Name | Type | Mandatory | Default | Description |\n| -------- | -------- | -------- | -------- | -------- |\n| type | String | yes | | The correlation id strategy type. |\n| parameterIndex | Number | yes | | The parameter index to use within the correlation strategy. |\n\n-   **Success Response:**\n    -   **Code:** 200  \n        **Content:**\n\n```json\n{\n    \"id\": \"event-identifier\"\n}\n```\n\n### Hard Coded Configuration\nStatic events can be configured within the application.yml file of Eventeum.\n\n```yaml\neventFilters:\n  - id: RequestCreated\n    contractAddress: ${CONTRACT_ADDRESS:0x4aecf261541f168bb3ca65fa8ff5012498aac3b8}\n    eventSpecification:\n      eventName: RequestCreated\n      indexedParameterDefinitions:\n        - position: 0\n          type: BYTES32\n        - position: 1\n          type: ADDRESS\n      nonIndexedParameterDefinitions:\n        - position: 2\n          type: BYTES32\n    correlationId:\n      type: NON_INDEXED_PARAMETER\n      index: 0\n```\n\n## Un-Registering Events\n\n### REST\n\n-   **URL:** `/api/rest/v1/event-filter/{event-id}`    \n-   **Method:** `DELETE`\n-   **Headers:**  `N/A`\n-   **URL Params:** `N/A`\n-   **Body:** `N/A`\n\n-   **Success Response:**\n    -   **Code:** 200\n        **Content:** `N/A`\n\n## Listing Registered Events\n\n### REST\n\n-   **URL:** `/api/rest/v1/event-filter`    \n-   **Method:** `GET`\n-   **Headers:**  \n\n| Key | Value |\n| -------- | -------- |\n| accept | application/json |\n\n-   **URL Params:** `N/A`\n\n-   **Response:** List of contract event filters:\n```json\n[{\n\t\"id\": \"event-identifier-1\",\n\t\"contractAddress\": \"0x1fbBeeE6eC2B7B095fE3c5A572551b1e260Af4d2\",\n\t\"eventSpecification\": {\n\t\t\"eventName\": \"TestEvent\",\n\t\t\"indexedParameterDefinitions\": [\n\t\t  {\"position\": 0, \"type\": \"UINT256\"},\n\t\t  {\"position\": 1, \"type\": \"ADDRESS\"}],\n\t\t\"nonIndexedParameterDefinitions\": [\n\t\t  {\"position\": 2, \"type\": \"BYTES32\"},\n\t\t  {\"position\": 3, \"type\": \"STRING\"}] },\n\t\"correlationIdStrategy\": {\n\t\t\"type\": \"NON_INDEXED_PARAMETER\",\n\t\t\"parameterIndex\": 0 }\n},\n....\n{\n\t\"id\": \"event-identifier-N\",\n\t\"contractAddress\": \"0x1fbBeeE6eC2B7B095fE3c5A572551b1e260Af4d2\",\n\t\"eventSpecification\": {\n\t\t\"eventName\": \"TestEvent\",\n\t\t\"indexedParameterDefinitions\": [\n\t\t  {\"position\": 0, \"type\": \"UINT256\"},\n\t\t  {\"position\": 1, \"type\": \"ADDRESS\"}],\n\t\t\"nonIndexedParameterDefinitions\": [\n\t\t  {\"position\": 2, \"type\": \"BYTES32\"},\n\t\t  {\"position\": 3, \"type\": \"STRING\"}] },\n\t\"correlationIdStrategy\": {\n\t\t\"type\": \"NON_INDEXED_PARAMETER\",\n\t\t\"parameterIndex\": 0 }\n}\n]\n```\n\n## Registering a Transaction Monitor\n\nFrom version 0.6.2, eventeum supports monitoring and broadcasting transactions. The matching criteria can be:\n\n- HASH: Monitor a single transaction hash. The monitoring will be removed once is notified.\n- FROM_ADDRESS: Monitor all transactions that are sent from a specific address.\n- TO_ADDRESS: Monitor all transactions that are received for a specific address.\n\n\nBesides on that, it can monitor the transaction for specific statuses: \n\n- FAILED: It will notify if the transaction has failed\n- CONFIRMED: It will notify if the transaction is confirmed.\n- UNCONFIRMED: In case the network is configured to wait for a certain number of confirmations, this will notify when is mined and not confirmed.\n\n### REST\n\nTo register a transaction monitor, use the below REST endpoint:\n\n-   **URL:** `/api/rest/v1/transaction?identifier=\u003ctxHash\u003e\u0026nodeName=\u003cnodeName\u003e`\n-   **Method:** `POST`\n-   **Headers:**  `N/A`\n-   **URL Params:** `N/A`\n    - identifier - The transaction hash to monitor\n    - nodeName - The node name that should be monitored\n-   **Body:**\n\nAn example with type `HASH`:\n\n```json\n{\n\t\"type\": \"HASH\",\n\t\"transactionIdentifierValue\": \"0x2e8e0f98be22aa1251584e23f792d43c634744340eb274473e01a48db939f94d\",\n\t\"nodeName\": \"defaultNetwork\",\n\t\"statuses\": [\"FAIlED\", \"CONFIRMATION\"]\n}\n```\n\n\nExample filtering by `FROM_ADDRES`, this will notify when a transactions fails with origin the address specified in the field `transactionIdentifierValue`\n\n```json\n{\n\t\"type\": \"FROM_ADDRESS\" ,\n\t\"transactionIdentifierValue\": \"0x1fbBeeE6eC2B7B095fE3c5A572551b1e260Af4d2\",\n\t\"nodeName\": \"defaultNetwork\",\n\t\"statuses\": [\"FAIlED\"]\n}\n```\n\n\n| Name | Type | Mandatory | Default | Description |\n| -------- | -------- | -------- | -------- | -------- |\n| type | String | yes | | The type of the filter you want to create: `HASH`, `FROM_ADDRESS`, `TO_ADDRESS` |\n| transactionIdentifierValue | String | yes |  | The value associated with the type. It should be the tx hash for `HASH` and the address of the contract in the other cases. |\n| nodeName | String | yes | default | The identifier of the node you want to listen the transaction |\n| statuses | List | no | ['FAILED', 'CONFIRMED'] | It will specify the statuses you want to be notified. The default is failed and confirmed transactions. The options are: `FAILED`, `CONFIRMED`, `UNCONFIRMED`, `INVALIDATED` |\n\n\n-   **Success Response:**\n    -   **Code:** 200\n        **Content:**\n\n```json\n{\n    \"id\": \"transaction-monitor-identifier\"\n}\n```\n\n## Un-Registering a Transaction Monitor\n\n### REST\n\n-   **URL:** `/api/rest/v1/transaction/{monitor-id}`\n-   **Method:** `DELETE`\n-   **Headers:**  `N/A`\n-   **URL Params:** `N/A`\n-   **Body:** `N/A`\n\n-   **Success Response:**\n    -   **Code:** 200  \n        **Content:** `N/A`\n\n## Broadcast Messages Format\n\n###  Contract Events\nWhen a subscribed event is emitted, a JSON message is broadcast to the configured kafka topic or rabbit exchange (contract-events by default), with the following format:\n\n```json\n{\n\t\"id\":\"unique-event-id\",\n\t\"type\":\"CONTRACT_EVENT\",\n\t\"details\":{\n\t\t\"name\":\"DummyEvent\",\n\t\t\"filterId\":\"63da468c-cec6-49aa-bea4-eeba64fb1df4\",\n\t\t\"indexedParameters\":[{\"type\":\"bytes32\",\"value\":\"BytesValue\"},\n\t\t\t{\"type\":\"address\",\"value\":\"0x00a329c0648769a73afac7f9381e08fb43dbea72\"}],\n\t\t\"nonIndexedParameters\":[{\"type\":\"uint256\",\"value\":10},\n\t\t\t{\"type\":\"string\",\"value\":\"StringValue\"}],\n\t\t\"transactionHash\":\"0xe4fd0f095990ec471cdf40638336a73636d2e88fc1a240c20b45101b9cce9438\",\n\t\t\"logIndex\":0,\n\t\t\"blockNumber\":258,\n\t\t\"blockHash\":\"0x65d1956c2850677f75ec9adcd7b2cfab89e31ad1e7a5ba93b6fad11e6cd15e4a\",\n\t\t\"address\":\"0x9ec580fa364159a09ea15cd39505fc0a926d3a00\",\n\t\t\"status\":\"UNCONFIRMED\",\n\t\t\"eventSpecificationSignature\":\"0x46aca551d5bafd01d98f8cadeb9b50f1b3ee44c33007f2a13d969dab7e7cf2a8\",\n\t\t\"id\":\"unique-event-id\"},\n\t\t\"retries\":0\n}\n\n```\n\n### Block Events\nWhen a new block is mined, a JSON message is broadcast to the configured kafka topic or rabbit exchange (block-events by default), with the following format:\n\n```json\n {\n \t\"id\":\"0x79799054d1782eb4f246b3055b967557148f38344fbd7020febf7b2d44faa4f8\",\n\t\"type\":\"BLOCK\",\n\t\"details\":{\n\t\t\"number\":257,\n\t\t\"hash\":\"0x79799054d1782eb4f246b3055b967557148f38344fbd7020febf7b2d44faa4f8\",\n\t\t\"timestamp\":12345678},\n\t\"retries\":0\n}\n```\n\n\n### Transaction Events\nWhen a new transaction that matches a transaction monitor is mined, a JSON message is broadcast to the configured kafka topic or rabbit exchange (transaction-events by default), with the following format:\n\n```json\n {\n \t\"id\":\"0x1c0482642861779703a34f4539b3ba18a0fddfb16558f3be7157fdafcaf2c030\",\n\t\"type\":\"TRANSACTION\",\n\t\"details\":{\n\t\t\"hash\":\"0x1c0482642861779703a34f4539b3ba18a0fddfb16558f3be7157fdafcaf2c030\",\n\t\t\"nonce\":\"0xf\",\n\t\t\"blockHash\":\"0x6a68edf369ba4ddf93aa31cf5871ad51b5f7988a69f1ddf9ed09ead8b626db48\",\n\t\t\"blockNumber\":\"0x1e1\",\n\t\t\"transactionIndex\":\"0x0\",\n\t\t\"from\":\"0xf17f52151ebef6c7334fad080c5704d77216b732\",\n\t\t\"to\":\"0xc5fdf4076b8f3a5357c5e395ab970b5b54098fef\",\n\t\t\"value\":\"0x16345785d8a0000\",\n\t\t\"nodeName\":\"default\",\n\t\t\"status\":\"CONFIRMED\"},\n\t\"retries\":0\n}\n```\n\n#### Contract Creation Transaction\nIf the transaction is a contract creation transaction, then the `contractAddress` value will be set to the address of the newly deployed smart contract.\n\n#### Transaction Event Statuses\n\nA broadcast transaction event can have the following statuses:\n\n| Status | Description |\n| -------- | -------- |\n| UNCONFIRMED | Transaction has been mined and we're now waiting for the configured number of blocks |\n| CONFIRMED | The configured number of blocks have been mined since the transaction has been mined |\n| INVALIDATED | The blockchain has forked since the initially broadcast UNCONFIRMED transaction was broadcast |\n| FAILED | The transaction has been mined but the tx execution failed |\n\n## Configuration\nEventeum can either be configured by:\n\n1. storing an `application.yml` next to the built JAR (copy one from `config-examples`). This overlays the defaults from `server/src/main/resources/application.yml`.\n2. Setting the associated environment variables.\n\n| Env Variable | Default | Description |\n| -------- | -------- | -------- |\n| SERVER_PORT | 8060 | The port for the eventeum instance. |\n| ETHEREUM_BLOCKSTRATEGY | POLL | The strategy for obtaining block events from an ethereum node (POLL or PUBSUB). It will be overwritten by the specific node configuration. |\n| ETHEREUM_NODE_URL | http://localhost:8545 | The default ethereum node url. |\n| ETHEREUM_NODE_BLOCKSTRATEGY | POLL | The strategy for obtaining block events for the ethereum node (POLL or PUBSUB).\n| ETHEREUM_NODE_HEALTHCHECK_POLLINTERVAL | 2000 | The interval time in ms, in which a request is made to the ethereum node, to ensure that the node is running and functional. |\n| ETHEREUM_NODE_ADD_TRANSACTION_REVERT_REASON | false | In case of a failing transaction it indicates if Eventeum should get the revert reason. Currently not working for Ganache and Parity.\n| ETHEREUM_NUMBLOCKSTOREPLAY | 12 | Number of blocks to replay on node or service failure (ensures no blocks / events are missed on chain reorg) |\n| POLLING_INTERVAL | 10000 | The polling interval used by Web3j to get events from the blockchain. |\n| EVENTSTORE_TYPE | DB | The type of eventstore used in Eventeum. (See the Advanced section for more details) |\n| BROADCASTER_TYPE | KAFKA | The broadcast mechanism to use.  (KAFKA or HTTP or RABBIT) |\n| BROADCASTER_CACHE_EXPIRATIONMILLIS | 6000000 | The eventeum broadcaster has an internal cache of sent messages, which ensures that duplicate messages are not broadcast.  This is the time that a message should live within this cache. |\n| BROADCASTER_EVENT_CONFIRMATION_NUMBLOCKSTOWAIT | 12 | The number of blocks to wait (after the initial mined block) before broadcasting a CONFIRMED event |\n| BROADCASTER_EVENT_CONFIRMATION_NUMBLOCKSTOWAITFORMISSINGTX | 200 | After a fork, a transaction may disappear, and this is the number of blocks to wait on the new fork, before assuming that an event emitted during this transaction has been INVALIDATED |\n| BROADCASTER_EVENT_CONFIRMATION_NUMBLOCKSTOWAITBEFOREINVALIDATING | 2 | Number of blocks to wait before considering a block as invalid. |\n| BROADCASTER_MULTIINSTANCE | false | If multiple instances of eventeum are to be deployed in your system, this should be set to true so that the eventeum communicates added/removed filters to other instances, via kafka. |\n| BROADCASTER_HTTP CONTRACTEVENTSURL | | The http url for posting contract events (for HTTP broadcasting) |\n| BROADCASTER_HTTP BLOCKEVENTSURL | | The http url for posting block events (for HTTP broadcasting) |\n| BROADCASTER_BYTESTOASCII | false | If any bytes values within events should be converted to ascii (default is hex) |\n| BROADCASTER_ENABLE_BLOCK_NOTIFICATION | true | Boolean that indicates if want to receive block notifications or not. Set false to not receive that event. |\n| ZOOKEEPER_ADDRESS | localhost:2181 | The zookeeper address |\n| KAFKA_ADDRESSES | localhost:9092 | Comma seperated list of kafka addresses |\n| KAFKA_TOPIC_CONTRACT_EVENTS | contract-events | The topic name for broadcast contract event messages |\n| KAFKA_TOPIC_BLOCK_EVENTS | block-events | The topic name for broadcast block event messages |\n| KAFKA_TOPIC_TRANSACTION_EVENTS | transaction-events | The topic name for broadcast trasaction messages |\n| KAFKA_REQUEST_TIMEOUT_MS | 20000 | The duration after which a request timeouts |\n| KAFKA_ENDPOINT_IDENTIFICATION_ALGORITHM | null | The endpoint identification algorithm to validate server hostname using server certificate |\n| KAFKA_SASL_MECHANISM | PLAIN | The mechanism used for SASL authentication |\n| KAFKA_USERNAME | \"\" | The username used to connect to a SASL secured Kafka cluster |\n| KAFKA_PASSWORD | \"\" | The password used to connect to a SASL secured Kafka cluster |\n| KAFKA_SECURITY_PROTOCOL | PLAINTEXT | Protocol used to communicate with Kafka brokers |\n| KAFKA_RETRIES | 10 | The number of times a Kafka consumer will try to publish a message before throwing an error |\n| KAFKA_RETRY_BACKOFF_MS | 500 | The duration between each retry |\n| KEEP_ALIVE_DURATION | 15000 | Rpc http idle threads keep alive timeout in ms |\n| MAX_IDLE_CONNECTIONS| 10 | The max number of HTTP rpc idle threads at the pool |\n| SYNCINC_THRESHOLD | 60 | Number of blocks of difference to consider that eventeum is \"syncing\" with a node\n| SPRING_DATA_MONGODB_HOST | localhost | The mongoDB host (used when event store is set to DB) |\n| SPRING_DATA_MONGODB_PORT | 27017 | The mongoDB post (used when event store is set to DB) |\n| RABBIT_ADDRESS | localhost:5672 | property spring.rabbitmq.host (The rabbitmq address) |\n| RABBIT_EXCHANGE | ThisIsAExchange | property rabbitmq.exchange |\n| RABBIT_ROUTING_KEY | thisIsRoutingKey | property rabbitmq.routingKeyPrefix |\n| DATABASE_TYPE | MONGO | The database to use.  Either MONGO or SQL. |\n| CONNECTION_TIMEOUT | 7000 | RPC, http connection timeout in millis |\n| READ_TIMEOUT | 35000 | RPC, http read timeout in millis |\n\n### INFURA Support Configuration\nConnecting to an INFURA node is only supported if connecting via websockets (`wss://\u003c...\u003e` node url).  The blockstrategy must also be set to PUBSUB.\n\n## Advanced\n### Correlation Id Strategies (Kafka Broadcasting)\n\nEach subscribed event can have a correlation id strategy association with it, during subscription.  A correlation id strategy defines what the kafka message key for a broadcast event should be, and allows the system to be configured so that events with particular parameter values are always sent to the same partition.\n\nCurrently supported correlation id strategies are:\n\n**Indexed Parameter Strategy** - An indexed parameter within the event is used as the message key when broadcasting.\n**Non Indexed Parameter Strategy** - An non-indexed parameter within the event is used as the message key when broadcasting.\n\n### Event Store\n\nEventeum utilises an event store in order to establish the block number to start event subscriptions from, in the event of a failover.  For example, if the last event broadcast for event with id X had a block number of 123, then on a failover, eventeum will subscribe to events from block 124.\n\nThere are currently 2 supported event store implementations:\n\n#### MongoDB\n\nBroadcast events are saved and retrieved from a mongoDB database.\n\n**Required Configuration**\n\n| Env Variable | Default | Description |\n| -------- | -------- | -------- |\n| EVENTSTORE_TYPE | DB | MongoDB event store enabled |\n| SPRING_DATA_MONGODB_HOST | localhost | The mongoDB host |\n| SPRING_DATA_MONGODB_PORT | 27017 | The mongoDB post |\n\n#### REST Service\n\nEventeum polls an external REST service in order to obtain a list of events broadcast for a specific event specification.  It is assumed that this REST service listens for broadcast events on the kafka topic and updates its internal state...broadcast events are not directly sent to the REST service by eventeum.\n\nThe implemented REST service should have a pageable endpoint which accepts a request with the following specification:\n\n-   **URL:** Configurable, defaults to `/api/rest/v1/event`    \n-   **Method:** `GET`\n-   **Headers:**  \n\n| Key | Value |\n| -------- | -------- |\n| content-type | application/json |\n\n-   **URL Params:**\n\n| Key | Value |\n| -------- | -------- |\n| page | The page number |\n| size | The page size |\n| sort | The results sort field |\n| dir | The results sort direction |\n| signature | Retrieve events with the specified event signature |\n\n-   **Body:** `N/A`\n\n-   **Success Response:**\n    -   **Code:** 200  \n        **Content:**\n\n```json\n{\n\t\"content\":[\n\t\t{\"blockNumber\":10,\"id\":\u003cunique event id\u003e}],\n\t\"page\":1,\n\t\"size\":1,\n\t\"totalElements\":1,\n\t\"first\":false,\n\t\"last\":true,\n\t\"totalPages\":1,\n\t\"numberOfElements\":1,\n\t\"hasContent\":true\n}\n```\n\n**Required Configuration**\n\n| Env Variable | Default | Description |\n| -------- | -------- | -------- |\n| EVENTSTORE_TYPE | REST | REST event store enabled |\n| EVENTSTORE_URL  | http://localhost:8081/api/rest/v1 | The REST endpoint url |\n| EVENTSTORE_EVENTPATH | /event | The path to the event REST endpoint |\n\n### Integrating Eventeum into Third Party Spring Application\n\nEventeum can be embedded into an existing Spring Application via an annotation.\n\n#### Steps to Embed\n\n1. Add the Eventeum Artifactory repository into your `pom.xml` file:\n\n```xml\n\u003crepositories\u003e\n  \u003crepository\u003e\n    \u003cid\u003eeventeum-artifactory\u003c/id\u003e\n    \u003curl\u003ehttps://eventeum.jfrog.io/artifactory/eventeum\u003c/url\u003e\n  \u003c/repository\u003e\n\u003c/repositories\u003e\n```\n\n2. Add the eventeum-core dependency to your `pom.xml` file:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.eventeum\u003c/groupId\u003e\n  \u003cartifactId\u003eeventeum-core\u003c/artifactId\u003e\n  \u003cversion\u003e*LATEST_EVENTEUM_VERSION*\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n3. Within your Application class or a `@Configuration` annotated class, add the `@EnableEventeum` annotation.\n\n#### Health check endpoint\n\nEventeum offers a healthcheck url where you can ask for the status of the systems you are using. It will look like:\n\n```\n{\n   \"status\":\"UP\",\n   \"details\":{\n      \"rabbit\":{\n         \"status\":\"UP\",\n         \"details\":{\n            \"version\":\"3.7.13\"\n         }\n      },\n      \"mongo\":{\n         \"status\":\"UP\",\n         \"details\":{\n            \"version\":\"4.0.8\"\n         }\n      }\n   }\n}\n```\n\nReturning this information it is very easy to create alerts over the status of the system.\n\nThe endpoint is: GET /monitoring/health\n\n## Metrics: Prometheus\n\nEventeum includes a prometheus metrics export endpoint.\n\nIt includes standard jvm, tomcat metrics enabled by spring-boot https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-metrics-export-prometheus https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-metrics-meter.\n\nAdded to the standard metrics, custom metrics have been added:\n\n* eventeum_%Network%_syncing: 1 if node is syncing (latestBlock + syncingThreshols \u003c currentBlock). 0 if not syncing\n* eventeum_%Network%_latestBlock: latest block read by Eventeum\n* eventeum_%Network%_currentBlock: Current node block\n* eventeum_%Network%_status: Current node status. 0 = Suscribed, 1 = Connected, 2 = Down\n\nAll  metrics include application=\"Eventeum\",environment=\"local\" tags.\n\nThe endpoint is: GET /monitoring/prometheus\n\n\n## Known Caveats / Issues\n* In multi-instance mode, where there is more than one Eventeum instance in a system, your services are required to handle duplicate messages gracefully, as each instance will broadcast the same events.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feventeum%2Feventeum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feventeum%2Feventeum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feventeum%2Feventeum/lists"}