docs: consolidate on deploy-quicknode-filter.sh as single source of truth

The repo had two conflicting paths for QuickNode filter deployment:
1. bin/update-quicknode-filter.js → infra/quicknode.tf (legacy, never worked)
2. bin/deploy-quicknode-filter.sh → QuickNode template API (current, working)

The Terraform path was always dead: ignore_all_server_changes=true prevents
Terraform from pushing filter_function changes to existing webhooks.

Changes:
- Delete bin/update-quicknode-filter.js (zombie script)
- Remove dead dev:webhook:* npm scripts that invoked it
- Add prominent deprecation notice to infra/quicknode.tf explaining that
  filter_function blobs are not deployed and all updates go via the script
- Rewrite README.md QuickNode section to document the actual deploy workflow
- Rewrite ADDING_EVENTS.md to replace Terraform migration steps with
  deploy-quicknode-filter.sh instructions
- Document the contracts address filtering quirk (silently ignored by
  QuickNode API — filtering must be done in the Cloud Function handler)

Author: gisk0

ADDING_EVENTS.md

@@ -55,17 +55,20 @@ function main(data) {
 }
 ```
 
-**Enable hot-reload** to automatically update the filter function in Terraform:
+**Deploy the updated filter to QuickNode** using the deploy script:
 
 ```bash
-# For governance events
-npm run dev:webhook:governor
+# Deploy a specific webhook
+./bin/deploy-quicknode-filter.sh --webhook healthcheck   # SortedOracles
+./bin/deploy-quicknode-filter.sh --webhook governor      # MentoGovernor
 
-# For oracle/sorted-oracles events
-npm run dev:webhook:healthcheck
+# Deploy both
+./bin/deploy-quicknode-filter.sh
 ```
 
-This watches for changes to your filter function file and automatically base64-encodes it into [`infra/quicknode.tf`](infra/quicknode.tf).
+The deploy script reads the ABI and contract addresses from the `/* template: evmAbiFilter ... */` comment header at the top of each filter file and applies the update live via `PATCH /webhooks/{id}/template/evmAbiFilterGo` (no downtime required).
+
+> **Note:** The old `npm run dev:webhook:*` scripts and `bin/update-quicknode-filter.js` are legacy — they updated `infra/quicknode.tf` which is never applied to live webhooks (`ignore_all_server_changes = true`). Use `deploy-quicknode-filter.sh` instead.
 
 #### 3. Test the Filter Function with Real Blockchain Data
 
@@ -104,36 +107,29 @@ Once your filter function works correctly:
 
 **Pro tip:** Using real data ensures your fixture accurately represents what QuickNode will send in production.
 
-#### 5. Clean Up and Migrate to Terraform
+#### 5. Clean Up and Make Permanent
 
-1. **Delete the temporary webhook** from the [QuickNode Webhooks Dashboard](https://dashboard.quicknode.com/webhooks)
-1. **Write Terraform code** in [`infra/quicknode.tf`](infra/quicknode.tf) to automate webhook creation:
+1. **Delete the temporary test webhook** from the [QuickNode Webhooks Dashboard](https://dashboard.quicknode.com/webhooks) (the one you created manually for testing).
 
-```hcl
-resource "quicknode_webhook" "your_event_webhook" {
-  name              = "Your Event Webhook"
-  url               = google_cloudfunctions2_function.watchdog_notifications.url
-  network           = "celo-mainnet"
-  dataset           = "block"
-  enabled           = true
+2. **Update the filter file comment header** with your final ABI and contract address:
 
-  filter_function = base64encode(file("${path.module}/quicknode-filter-functions/your-filter.js"))
+   ```js
+   /*
+   template: evmAbiFilter
+   abi: [{...your trimmed ABI events...}]
+   contracts: 0xYourContractAddress
+   */
+   ```
 
-  headers = {
-    "X-AUTH-TOKEN" = var.x_auth_token
-  }
-}
-```
+   Keep only the events your handler actually uses — this reduces Cloud Function invocation volume.
 
-1. **Deploy the webhook via Terraform**:
+3. **Deploy to the permanent webhook** via:
 
-```bash
-cd infra
-terraform plan   # Review changes
-terraform apply  # Create the webhook
-```
+   ```bash
+   ./bin/deploy-quicknode-filter.sh --webhook <healthcheck|governor>
+   ```
 
-**Note:** If updating an existing webhook's filter function, you may need to pause it first or destroy and recreate it (see [README](README.md#workflow) for details).
+   > **Note:** Terraform (`infra/quicknode.tf`) manages webhook _creation_ but cannot update filter configuration on existing webhooks (`ignore_all_server_changes = true`). All filter updates go through `bin/deploy-quicknode-filter.sh`.
 
 ### Part 2: Implement TypeScript Event Handler
 

README.md

@@ -209,55 +209,40 @@ The centralized event system makes adding new events straightforward—just upda
 
 ## Developing QuickNode Webhook Filter Functions
 
-QuickNode webhooks use [JavaScript filter functions](https://www.quicknode.com/docs/streams/filters?#example-filter-functions) that run on QuickNode's servers to determine which blockchain events should trigger notifications to our Cloud Function. These filters are base64-encoded and stored in [`infra/quicknode.tf`](./infra/quicknode.tf) under the `filter_function` properties.
+QuickNode webhooks use the `evmAbiFilter` template to match blockchain events by ABI event signature. Filter configuration (ABI and contract addresses) lives in the comment header of each filter file under [`infra/quicknode-filter-functions/`](./infra/quicknode-filter-functions/).
 
-### Workflow
+> **Note:** The `filter_function` base64 blobs in `infra/quicknode.tf` and the old `bin/update-quicknode-filter.js` script are **legacy artefacts**. They are not deployed — `ignore_all_server_changes = true` in Terraform prevents Terraform from pushing any changes to existing webhooks. All deploys go through `bin/deploy-quicknode-filter.sh`.
 
-1. [OPTIONAL] If you want to first double-check which code is actually deployed right now:
-   - Navigate to the [QuickNode Webhooks Dashboard](https://dashboard.quicknode.com/webhooks)
-   - Click the Webhook you're developing
-   - Copy the webhook ID from the URL into your clipboard
-   - Obtain the current filter function via:
+### Workflow
 
-     ```bash
-     curl -X GET \
-        "https://api.quicknode.com/webhooks/rest/v1/webhooks/$webhook_id" \
-        -H "accept: application/json" \
-        -H "x-api-key: $quicknode_api_key" \
-        | jq -r .filter_function \
-        | base64 -d
-     ```
+1. **Edit the filter file** at [`infra/quicknode-filter-functions/sorted-oracles.js`](./infra/quicknode-filter-functions/sorted-oracles.js) or [`governor.js`](./infra/quicknode-filter-functions/governor.js).
 
-2. **Open the filter function** in plain JavaScript at [`infra/quicknode-filter-functions/sorted-oracles.js`](./infra/quicknode-filter-functions/sorted-oracles.js)
+   The comment header at the top of each file is the deployment source of truth:
+   ```js
+   /*
+   template: evmAbiFilter
+   abi: [{...}]
+   contracts: 0xYourContractAddress
+   */
+   ```
 
-3. **Enable hot-reload** to automatically update the Terraform file:
+2. **Deploy to QuickNode** using the deploy script:
 
    ```sh
-   # Run the cmd for the webhook you're interested in
-   npm run dev:webhook:healthcheck
+   ./bin/deploy-quicknode-filter.sh --webhook healthcheck   # SortedOracles
+   ./bin/deploy-quicknode-filter.sh --webhook governor      # MentoGovernor
+   ./bin/deploy-quicknode-filter.sh                         # both
    ```
 
-   This will watch for changes to `sorted-oracles.js` (which we're using as the healthcheck) and automatically:
-   - Base64 encode the updated function
-   - Update the `filter_function` field in the `quicknode_webhook_healthcheck` resource in `quicknode.tf`
-   - Create a timestamped backup of `quicknode.tf` before making changes
-
-4. **Make your changes** to `sorted-oracles.js` and save the file. The script will automatically update `quicknode.tf`.
+   This reads the ABI and contract addresses from the comment header, builds the `templateArgs` payload, and calls `PATCH /webhooks/{id}/template/evmAbiFilterGo` to apply the update live (no downtime).
 
-5. **Review the changes** with `git diff infra/quicknode.tf` to ensure the filter function was updated correctly.
+3. **Verify** by checking the [QuickNode Webhooks Dashboard](https://dashboard.quicknode.com/webhooks) or inspecting the raw webhook via:
 
-6. **Deploy to QuickNode**:
-
-   ```sh
-   cd infra
-   terraform plan   # Review changes
-   terraform apply  # Deploy
+   ```bash
+   curl -X GET "https://api.quicknode.com/webhooks/rest/v1/webhooks/$webhook_id" \
+     -H "x-api-key: $quicknode_api_key"
    ```
 
-   **⚠️ Important:** QuickNode rejects updates to active webhooks. You must either:
-   - Pause the webhook first (set `status = "paused"` in the resource, run `terraform apply`, then update the filter function, then set `status = "active"` and `terraform apply` again)
-   - OR comment out the webhook resource, `terraform apply` to delete it, uncomment with your changes, and `terraform apply` to recreate it
-
 ### Filter Function Structure
 
 The filter functions follow QuickNode's `evmAbiFilter` template:
@@ -267,6 +252,8 @@ The filter functions follow QuickNode's `evmAbiFilter` template:
 - They can include custom filtering logic (e.g., filtering by specific token addresses)
 - They return matching events or `null` if no matches found
 
+> **Important quirk:** The `evmAbiFilter` template filters by topic hash only — the `contracts` address filter in `templateArgs` is currently **silently ignored** by QuickNode's API. All addresses that emit a matching event signature will trigger the webhook. Address filtering must be done in the Cloud Function handler.
+
 See the [QuickNode Webhooks documentation](https://www.quicknode.com/docs/webhooks/getting-started) for more details on filter function syntax.
 
 ## Deploying from Scratch

bin/update-quicknode-filter.js

@@ -1,3 +1,17 @@
+# ⚠️  IMPORTANT: The `filter_function` blobs in this file are NOT the deployment source of truth.
+#
+# These base64-encoded JS blobs were used historically, but `ignore_all_server_changes = true`
+# prevents Terraform from ever pushing filter changes to existing webhooks. The live webhook
+# configuration is managed separately via `bin/deploy-quicknode-filter.sh`, which reads the
+# ABI and contracts from the comment header in each filter file and calls the QuickNode
+# template API directly.
+#
+# To update a webhook filter, edit the comment header in the relevant filter file
+# (infra/quicknode-filter-functions/*.js) and run:
+#   ./bin/deploy-quicknode-filter.sh --webhook <healthcheck|governor>
+#
+# Terraform is only used here to CREATE webhooks (on initial bootstrap). Updates use the script.
+#
 # 🚨 Note: The QuickNode API rejects updates to active webhooks
 #
 # It needs to be paused before updating. To update one of the below webhooks EITHER:

infra/quicknode.tf

@@ -12,7 +12,6 @@
     "deploy:function": "./bin/deploy-via-gcloud.sh",
     "destroy": "terraform -chdir=infra destroy",
     "dev": "nodemon --ext ts --ignore dist --exec \"npm run start\"",
-    "dev:webhook:healthcheck": "nodemon --watch infra/quicknode-filter-functions/sorted-oracles.js --exec \"node bin/update-quicknode-filter.js\"",
     "gcp-build": "npm run build",
     "generate:env": "terraform -chdir=infra apply -target=local_file.env_file",
     "logs": "./bin/get-logs.sh",