@avaprotocol/sdk-js 2.15.0 → 2.16.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @avaprotocol/sdk-js
 
+## 2.16.0
+
+### Minor Changes
+
+- 44f1764: Document the new `value` / `valueFormatted` field semantics for ERC-20 Transfer event triggers and document that `MethodCallType.applyToFields: ["Transfer.value"]` is no longer needed (and should not be used) for Transfer events. The `applyToFields` field itself is **not** deprecated — it remains the correct mechanism for non-Transfer cases like Chainlink `AnswerUpdated.current`, ERC-20 `totalSupply`, and other contract read fields where shared enrichment does not pre-compute a formatted value.
+
+  **Breaking change in trigger output (originates from EigenLayer-AVS PR #509):**
+
+  - `EventTrigger` output `data.value` is now the **raw uint256 base-units string** for ERC-20 `Transfer` events (e.g. `"1500000"` for 1.5 USDC). Previously this field held the decimal-formatted amount when token metadata was available.
+  - `data.valueFormatted` is the new field for the **decimal-applied display string** (e.g. `"1.5"`).
+  - SDK consumers that read `data.value` for display **must migrate to `data.valueFormatted`**. Code that does math/encoding on `data.value` (e.g. ERC-20 transfer calldata generation) is unchanged or now more correct.
+
+  **Guidance change (not a type-level deprecation):**
+
+  - `MethodCallType.applyToFields: ["Transfer.value"]` is no longer needed for ERC-20 Transfer events — the operator's shared event enrichment now always publishes `valueFormatted` for Transfer events when token decimals are known, making the opt-in mechanism redundant and potentially double-formatting. **`applyToFields` itself is not deprecated** — it remains valid (and required) for non-Transfer use cases.
+
+  **Updates in this release:**
+
+  - `packages/types/src/shared.ts` — `MethodCallType.applyToFields` JSDoc clarified with an `@remarks` block explaining the Transfer-specific guidance. No `@deprecated` tag (which would incorrectly strikethrough the 30+ legitimate non-Transfer usages across `contractRead.test.ts`, `loopNode.test.ts`, Chainlink/Uniswap templates, etc.).
+  - `packages/sdk-js/README.md` — new "Event trigger output: `value` vs `valueFormatted`" section.
+  - `examples/example.ts` — comment on the `scheduleMonitorTransfer` ContractWrite step explaining when to use `data.value` vs `data.valueFormatted`.
+  - Test fixtures and assertions in `tests/triggers/eventTrigger.test.ts`, `tests/templates/telegram-alert-on-transfer.test.ts`, and `tests/executions/stepInput.test.ts` updated to use the new field semantics.
+
+  No production SDK code reads `transferData.value` directly, so there is no API surface break — this is a documentation and consumer-guidance release.
+
+### Patch Changes
+
+- bb0b404: Address PR review feedback on the Transfer field semantics alignment (companion to the previous changeset, `transfer-value-semantics.md`).
+
+  **Bug fix in `examples/example.ts`** — the `scheduleMonitorTransfer` ContractWrite calldata template was using `Number(demoTriggerName.data.value).toString(16)` to encode the ERC-20 transfer amount. With `data.value` now being raw uint256 base units (per EigenLayer-AVS PR #509), the `Number(...)` cast silently loses precision for any token amount above JavaScript's safe-integer range (~9e15 — about 9 ETH or 9,000,000,000 USDC), producing incorrect transfer calldata. Switched to `BigInt(...)` which is integer-safe.
+
+  **Test determinism fix in `tests/executions/stepInput.test.ts`** — the previous attempt added an `if (eventData.valueFormatted) { ... } else { decode rawData }` fallback in the CustomCode snippet. That violated the test determinism rule (CLAUDE.md) because it allowed the test to pass via two different code paths and would have hidden a future regression that drops `valueFormatted` from the simulator output. The CustomCode snippet now reads `eventData.valueFormatted` directly. As a side effect, this also removes a `parseInt(rawValue, 16)` precision-loss path that would have silently truncated large amounts on the fallback branch.
+
+  **Documentation polish** — `packages/sdk-js/README.md` previously said "Breaking change in v1.x" but `@avaprotocol/sdk-js` is currently v2.x. Replaced with version-agnostic wording: "Breaking change in operator output (EigenLayer-AVS PR #509)".
+
+  **Comment alignment** — two inline comments in the Transfer event tests still used the word "deprecated", which contradicted the deliberate `@remarks`-not-`@deprecated` decision in the previous changeset. Updated to "is no longer needed for Transfer events" and explicitly noted the field is still valid for non-Transfer cases (Chainlink AnswerUpdated, ERC-20 totalSupply, etc.).
+
+  No SDK API surface changes. No new tests added beyond the determinism cleanup. The semantic regex assertions added in the previous PR continue to pin the `value` / `valueFormatted` contract.
+
+- Updated dependencies [44f1764]
+  - @avaprotocol/types@2.12.0
+
 ## 2.15.0
 
 ### Minor Changes

package/README.md

@@ -113,6 +113,21 @@ export async function getAuthKey(
 }
 ```
 
+## Event trigger output: `value` vs `valueFormatted`
+
+When an `EventTrigger` matches an ERC-20 `Transfer`, the operator's shared event enrichment publishes both a raw and a formatted amount on the trigger's output `data`:
+
+| Field | Type | Meaning | Use for |
+|---|---|---|---|
+| `data.value` | `string` | Raw uint256 base units (e.g. `"1500000"` for 1.5 USDC) | Math, encoding ERC-20 calldata, BigInt operations |
+| `data.valueFormatted` | `string` | Decimal-applied display string (e.g. `"1.5"`) | Telegram/email messages, UI rendering |
+| `data.tokenSymbol` | `string` | Token symbol from contract metadata | Display |
+| `data.tokenDecimals` | `number` | Token decimals from contract metadata | Reference |
+
+**Breaking change in operator output (EigenLayer-AVS PR #509)**: Prior operator versions populated `data.value` with the decimal-formatted amount when token metadata was available. After PR #509, `data.value` is **always raw uint256 base units**, and `data.valueFormatted` is the new field for human-readable amounts. SDK consumers that read `data.value` for display **must migrate to `data.valueFormatted`**.
+
+**Do not use `MethodCallType.applyToFields: ["Transfer.value"]`** for ERC-20 Transfer events — the enrichment is now automatic and `applyToFields` would be redundant (and may double-format). `applyToFields` remains the correct mechanism for every other use case where shared enrichment does not pre-compute a formatted value (Chainlink AnswerUpdated `current`/`answer`, ERC-20 `totalSupply`, generic contract read fields, etc.).
+
 ## Contributing
 
 We welcome contributions! Feel free to submit pull requests or open issues for any bugs or feature requests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avaprotocol/sdk-js",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "description": "A JavaScript/TypeScript SDK designed to simplify integration with Ava Protocol's AVS",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -31,7 +31,7 @@
     "prepare": "node ../../scripts/prepare-package.js"
   },
   "dependencies": {
-    "@avaprotocol/types": "2.11.0",
+    "@avaprotocol/types": "2.12.0",
     "@grpc/grpc-js": "^1.11.3",
     "@grpc/proto-loader": "^0.7.13",
     "dotenv": "^16.4.5",