{"id":18369942,"url":"https://github.com/cawfree/countersoiree","last_synced_at":"2025-10-09T19:12:33.266Z","repository":{"id":88543292,"uuid":"541213439","full_name":"cawfree/countersoiree","owner":"cawfree","description":"💃 🧪 GraphQL for the Ethereum mempool.","archived":false,"fork":false,"pushed_at":"2022-09-29T07:55:34.000Z","size":258,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-06T18:38:40.167Z","etag":null,"topics":["ethereum","evm","graphql","mempool"],"latest_commit_sha":null,"homepage":"https://twitter.com/cawfree","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cawfree.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":"2022-09-25T15:17:55.000Z","updated_at":"2024-04-09T10:44:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"41fd1941-8ef2-4541-94a8-d530952e1718","html_url":"https://github.com/cawfree/countersoiree","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cawfree/countersoiree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawfree%2Fcountersoiree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawfree%2Fcountersoiree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawfree%2Fcountersoiree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawfree%2Fcountersoiree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cawfree","download_url":"https://codeload.github.com/cawfree/countersoiree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cawfree%2Fcountersoiree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001981,"owners_count":26083243,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ethereum","evm","graphql","mempool"],"created_at":"2024-11-05T23:34:08.060Z","updated_at":"2025-10-09T19:12:33.250Z","avatar_url":"https://github.com/cawfree.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# countersoiree 💃\n🧪 A [__GraphQL__](https://www.apollographql.com/) interface to the [__Ethereum__](https://ethereum.org) mempool.\n\nThe goal of this project is to enable developers to easily declare expressive filters that search for specific unmined, pending transactions.\n\nThere are a number of interesting applications that would be enabled via thorough inspection of the mempool, including but not limited to: profit searching, alerts generation, passive analysis, and active responses to pending transactions through the dispatch of higher-gas overrides.\n\n\u003e ⚠️ Fren, this project is still in development. Feel free to poke around, but don't get too attached.\n\n## 🍝 build from sauce\n\nTo build this project, just [__clone__](https://rogerdudler.github.io/git-guide/) the repository, install dependencies and configure your environment variables for this project.\n\nSince [`countersoiree`](https://github.com/cawfree/countersoiree) depends on using the ABI to parse input queries, it depends on [__etherscan__](https://etherscan.io) as a centralization vector to source smart contract interface definitions dynamically. To avoid single points of failure, a goal of this project is to enable the developer to manually supply contract ABI, or specify alternative providers.\n\n```shell\ngit clone https://github.com/cawfree/countersoiree\ncd countersoiree\nyarn\necho \"ETHERSCAN_KEY=\\\"YOUR_ETHERSCAN_KEY\\\"\" \u003e\u003e .env\nyarn test\n```\n\n## ✍️ usage\n\n[`countersoiree`](https://github.com/cawfree/countersoiree) projects pending transactions in the Ethereum mempool, interpreted via a [`ethers.providers.TransactionResponse`](https://docs.ethers.io/v5/api/providers/types/), onto a corresponding [__GraphQL Schema__](./schema.graphql). In turn, this permits any pending transactions polled using [`ethers`](https://ethers.io/) into a queryable interface.\n\n#### 1. Basic Example\n\nWe can pick fields of interest from the `pendingTransaction` collection, which uniquely identifies a single transaction from the mempool.\n\nIn practice, the contents of the mempool are accumulated asynchronously via WebSockets; therefore the `pendingTransaction` interface can be used as a boolean filter against a single transaction scalar:\n\n```graphql\n{\n  pendingTransaction {\n    to\n    from\n    hash\n    maxFeePerGas\n    maxPriorityFeePerGas\n  }\n}\n```\n\n#### 2. Using Filters\n\nWe can filter `pendingTransaction`s using query parameters. In the example below, we can pass a `string` scalar to the `\"to\"` property of the entity to ensure only match on a specific target address.\n\nHere, we specify that we only want to read the `data` field on pending transactions which target [__Seaport v1.1__](https://etherscan.io/address/0x00000000006c3852cbef3e08e8df289169ede581).\n\n```graphql\nquery SeaportTransactions {\n  pendingTransaction(\n    to: \"0x00000000006c3852cbEf3e08E8dF289169EdE581\"\n  ) {\n    data\n  }\n}\n```\n\nSo it's a little useful to be able to watch transactions at a specific contract address (at this point we are a glorified [__event listener__](https://docs.ethers.io/v5/api/providers/provider/#Provider--events)), but it'd be even better to only watch for specific function calls on the smart contract.\n\nIn the following example, we specify that we only want to match on pending transactions where the data property targets the `external` `fulfillBasicOrder` function:\n\n```graphql\nquery SeaportFulfillBasicOrderTransactions {\n  pendingTransaction(\n    to: \"0x00000000006c3852cbEf3e08E8dF289169EdE581\"\n    data: {\n      interface: \"function fulfillBasicOrder(tuple(address considerationToken, uint256 considerationIdentifier, uint256 considerationAmount, address offerer, address zone, address offerToken, uint256 offerIdentifier, uint256 offerAmount, uint8 basicOrderType, uint256 startTime, uint256 endTime, bytes32 zoneHash, uint256 salt, bytes32 offererConduitKey, bytes32 fulfillerConduitKey, uint256 totalOriginalAdditionalRecipients, tuple(uint256 amount, address recipient)[] additionalRecipients, bytes signature) parameters) payable returns (bool fulfilled)\"\n    }\n  ) {\n    data\n  }\n}\n```\n\nIn this instance, implementors must take care to specify the function signature correctly.\n\n\n#### 3. Querying Calldata\n\nWhen we specify the `\"interface\"` function signature and `\"to\"` address of pending transactions, [`countersoiree`](https://github.com/cawfre/countersoiree)  enables us to dive a little deeper into the [__calldata__](https://ethereum.stackexchange.com/questions/52989/what-is-calldata) itself, where we can configure comparison filters against the individual function parameters of incoming transactions.\n\nIn the snippet below, let's define a query where we search for all `fulfillBasicOrder` transactions on [__Seaport__](https://etherscan.io/address/0x00000000006c3852cbef3e08e8df289169ede581) that match the `offerer` of [`cawfree.eth`](https://etherscan.io/address/cawfree.eth):\n\n```graphql\nquery FulfillBasicOrdersForOffererAddressQuery {\n  pendingTransaction(\n    data: {\n      interface: \"function fulfillBasicOrder(tuple(address considerationToken, uint256 considerationIdentifier, uint256 considerationAmount, address offerer, address zone, address offerToken, uint256 offerIdentifier, uint256 offerAmount, uint8 basicOrderType, uint256 startTime, uint256 endTime, bytes32 zoneHash, uint256 salt, bytes32 offererConduitKey, bytes32 fulfillerConduitKey, uint256 totalOriginalAdditionalRecipients, tuple(uint256 amount, address recipient)[] additionalRecipients, bytes signature) parameters) payable returns (bool fulfilled)\"\n      parameters: {\n        offerer: \"0x312e71162Df834A87a2684d30562b94816b0f072\"\n      }\n    }\n  ) {\n    data\n  }\n}\n```\n\nNote that on the [__Seaport ABI__](https://api.etherscan.io/api?module=contract\u0026action=getabi\u0026address=0x00000000006c3852cbef3e08e8df289169ede581), `fulfillBasicOrder` accepts a single named argument, `\"parameters\"` which is a `tuple`:\n\n```\nfunction fulfillBasicOrder(tuple(address considerationToken, uint256 considerationIdentifier, uint256 considerationAmount, address offerer, address zone, address offerToken, uint256 offerIdentifier, uint256 offerAmount, uint8 basicOrderType, uint256 startTime, uint256 endTime, bytes32 zoneHash, uint256 salt, bytes32 offererConduitKey, bytes32 fulfillerConduitKey, uint256 totalOriginalAdditionalRecipients, tuple(uint256 amount, address recipient)[] additionalRecipients, bytes signature) parameters) payable returns (bool fulfilled)\n```\n\nTherefore, when we attempt to filter against `offerer` in our query, we are filtering on the nested field `\"offerer\"` of the `tuple` `\"parameters\"`, thus yielding:\n\n```graphql\nparameters: {\n  address: \"0x312e71162Df834A87a2684d30562b94816b0f072\"\n}\n```\n\n## ✌️ license\n[__MIT__](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcawfree%2Fcountersoiree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcawfree%2Fcountersoiree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcawfree%2Fcountersoiree/lists"}