release: align SDK with EigenLayer-AVS PR #509 Transfer field semantics

[chrisli30]

Summary

Documentation, type-comment, test-fixture, and changeset alignment with EigenLayer-AVS PR #509, which changed the semantics of TransferEventResponse.value for ERC-20 Transfer event triggers.

No production SDK source code reads transferData.value directly, so there is no compile-time API break. This is a documentation + consumer-guidance + test-fixture release.

What changed in EigenLayer-AVS

For ERC-20 Transfer event triggers, the operator's shared event enrichment now publishes:

Field	Type	Meaning
data.value	string	Raw uint256 base units (e.g. "1500000" for 1.5 USDC)
data.valueFormatted	string	Decimal-applied display string (e.g. "1.5")

Previously data.value held the formatted value when token metadata was available. SDK consumers that read data.value for display will now get raw base units and break.

Commits

SHA	Type	Summary
44f1764	docs	Align SDK with PR #509: type comment, README section, example.ts comment, test fixtures, changeset
a2afd43	test	Drop deprecated applyToFields ["Transfer.value"] from event trigger tests + add semantic regex assertions
668002b	docs	Scope Transfer value guidance to @remarks, not a field-level @deprecated (avoids strikethrough on 30+ legitimate non-Transfer usages)

Highlights

MethodCallType.applyToFields guidance, not deprecation (668002b)

The first attempt put @deprecated on MethodCallType.applyToFields. Audit found 30+ legitimate non-Transfer uses across contractRead.test.ts, loopNode.test.ts, eventTrigger.test.ts, uniswapv3_stoploss.test.ts, and the production wiring in models/trigger/event.ts / node/contractRead.ts / node/loop.ts (Chainlink AnswerUpdated.current/latestRoundData.answer, ERC-20 totalSupply, etc.). A blanket @deprecated would strikethrough all of them in IDE intellisense. The actual deprecation is value-specific (["Transfer.value"]), which TypeScript can't express at the type level. Replaced with an @remarks block that documents the Transfer-specific guidance without polluting non-Transfer usages.

Test cleanup + semantic contract assertion (a2afd43)

Removed the now-redundant methodCalls: [{ methodName: "decimals", applyToFields: ["Transfer.value"] }] blocks from tests/triggers/eventTrigger.test.ts (1 site) and tests/templates/telegram-alert-on-transfer.test.ts (2 sites). Added new semantic regex assertions in eventTrigger.test.ts that pin the PR #509 contract:

expect(transferData.value as string).toMatch(/^\d+$/);              // raw base units
expect(transferData.valueFormatted as string).toMatch(/^\d+(\.\d+)?$/); // decimal

These catch any future regression where the operator accidentally swaps the two fields back.

Documentation surface (44f1764)

• packages/sdk-js/README.md — new "Event trigger output: value vs valueFormatted" section with field semantics table and breaking-change callout
• examples/example.ts — comment on scheduleMonitorTransfer's ContractWrite step explaining when to use data.value (raw, for ERC-20 calldata) vs data.valueFormatted (display)
• .changeset/transfer-value-semantics.md — minor bump for @avaprotocol/sdk-js and @avaprotocol/types with the migration note

Test plan

• yarn build — both @avaprotocol/types and @avaprotocol/sdk-js build clean
• Verified TransferEvent test fixtures use the new field semantics (value: "100500000" + valueFormatted: "100.5" for USDC)
• Verified all applyToFields: ["Transfer.value"] configurations are removed from active test code (only mentioned in deprecation comments)
• Verified all 30+ non-Transfer applyToFields usages still render normally (no @deprecated strikethrough)
• Reviewers: confirm no in-flight workflow definitions in production rely on the old value semantics

[claude]

PR Review: align SDK with EigenLayer-AVS PR #509 Transfer field semantics

Overall this is a well-reasoned docs + test-fixture update. The commit history is clean, the @remarks decision (avoiding blanket @deprecated) is the right call, and the semantic regex assertions in eventTrigger.test.ts are a nice addition. A few issues to address:

---

Bug / Violation of Project Convention

stepInput.test.ts:522 — conditional fallback conflicts with test determinism rule

if (eventData.valueFormatted) {
  valueFormatted = parseFloat(eventData.valueFormatted);
} else {
  const rawValue = eventData.rawData || "0x0";
  const valueWei = parseInt(rawValue, 16);           // ⚠️ see precision note below
  valueFormatted = valueWei / Math.pow(10, 18);
}

CLAUDE.md states: "All test assertions must be deterministic — never use conditional checks that allow tests to pass on errors." Even though this conditional lives inside the CustomCode template string (not directly in an expect() call), it makes the test pass via two different code paths. The simulation path silently falls back to rawData decoding; the live-operator path uses valueFormatted. A regression that drops valueFormatted in the simulation would still produce a passing test via the fallback.

Since this is a simulation test, it will always hit the else branch (valueFormatted is not populated by the simulator). The if branch is dead code in this context. Consider either:

• removing the fallback entirely and asserting valueFormatted is defined upfront (deterministic), or
• adding a separate test that explicitly asserts valueFormatted is present in the simulation output and then uses it unconditionally.

---

Precision Issue in Fallback Code

stepInput.test.ts:526 — parseInt(rawValue, 16) silently loses precision for uint256 values above Number.MAX_SAFE_INTEGER (~9 × 10¹⁵). For a token with 18 decimals, 100 ETH = 100 * 10^18 = 10^20, which already exceeds the safe integer limit. This is pre-existing code, but this PR is adding context around numeric semantics so it's a good time to fix:

// Before:
const valueWei = parseInt(rawValue, 16);
const valueFormatted = valueWei / Math.pow(10, 18);

// After:
const valueWei = BigInt(rawValue);
const valueFormatted = Number(valueWei) / Math.pow(10, 18); // acceptable for display
// or more precisely:
const valueFormatted = Number(valueWei * 10000n / BigInt(10 ** 18)) / 10000;

Same note applies to the parseFloat(eventData.valueFormatted) call: for tokens with many decimals and large amounts the float representation may lose the last few digits. For display with _.floor(..., 4) it's probably fine in practice, but worth a comment.

---

Comment Inconsistency ("deprecated" language)

The third commit (668002b) was specifically about removing @deprecated to avoid IDE strikethrough pollution. However, two inline comments still use the word "deprecated":

• tests/templates/telegram-alert-on-transfer.test.ts:133-134:

  // `valueFormatted` automatically. applyToFields ["Transfer.value"]
  // is deprecated for this case.

• tests/triggers/eventTrigger.test.ts:838-839:

  // applyToFields: ["Transfer.value"] is deprecated for this
  // use case (see MethodCallType JSDoc and SDK README).

These contradict the deliberate @remarks-not-@deprecated decision. Suggest changing to "is no longer needed for this case" or "should not be used for Transfer events" to stay consistent with the JSDoc and changeset framing.

---

Minor: Changeset Semver

This is marked minor for both packages. The runtime behavior of data.value has changed from formatted → raw base units — consumers reading data.value for display will silently show wrong values (not a compile error). The SDK itself doesn't read this field, so there's no API surface break, but the practical impact for end consumers is a major-level behavioral change. Worth discussing whether this should be major or at least flagging it prominently in the release notes (the changeset body already does a good job of this).

---

Suggestion: Add a TransferEventData type

Now that value, valueFormatted, tokenSymbol, and tokenDecimals are well-defined and documented, a typed interface would help consumers catch misuse at compile time:

// packages/types/src/trigger.ts (or shared.ts)
export interface TransferEventData {
  value: string;           // raw uint256 base units
  valueFormatted: string;  // decimal-applied display string
  tokenSymbol: string;
  tokenDecimals: number;
  fromAddress: string;
  toAddress: string;
  blockNumber: number;
  transactionHash: string;
}

Not a blocker for this PR, but a natural follow-up given the documentation work done here.

---

Nit: README version reference is vague

**Breaking change in v1.x**: Prior versions populated `data.value` with...

"v1.x" doesn't tell consumers which specific version introduced this. Consider pinning the exact version (e.g., "as of v1.4.0") once the changeset lands, or replacing with "as of EigenLayer-AVS PR #509 / SDK v<X.Y.Z>".

---

Summary: The core approach is solid. The two required fixes before merge are (1) the determinism violation in stepInput.test.ts and (2) aligning the inline "deprecated" comments with the @remarks framing. The precision issue is worth addressing since this PR is already touching numeric semantics in that file.

[Copilot]

Pull request overview

Aligns the SDK’s documentation, type guidance, and test fixtures with EigenLayer-AVS PR #509, which changed ERC-20 Transfer event trigger output semantics so data.value is always raw base units and data.valueFormatted is the human-readable decimal string.

Changes:

• Updated trigger/template tests and fixtures to expect value as raw uint256 base-units string and to include/validate valueFormatted.
• Clarified MethodCallType.applyToFields JSDoc/README guidance to discourage ["Transfer.value"] usage for ERC-20 Transfer events (shared enrichment now provides valueFormatted).
• Added a changeset entry documenting the semantics/migration guidance.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/triggers/eventTrigger.test.ts	Removes Transfer decimals methodCalls and adds semantic assertions for value vs valueFormatted.
tests/templates/telegram-alert-on-transfer.test.ts	Removes applyToFields: ["Transfer.value"] and updates mocked Transfer output to include valueFormatted.
tests/executions/stepInput.test.ts	Prefers valueFormatted when present, preserving simulation fallback behavior.
packages/types/src/shared.ts	Adds @remarks guidance clarifying applyToFields usage and Transfer-specific caveat.
packages/sdk-js/README.md	Documents value vs valueFormatted semantics and migration guidance.
examples/example.ts	Adds comments describing new semantics near ERC-20 calldata encoding example.
.changeset/transfer-value-semantics.md	Adds release notes describing the semantics change and guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The README calls this a "Breaking change in v1.x", but @avaprotocol/sdk-js is currently v2.x (package.json shows 2.15.0). This version reference is inaccurate/misleading; consider changing it to "Breaking change relative to previous operator output" (or update it to the correct major) so readers don’t assume this only affects v1 consumers.

Suggested change

**Breaking change in v1.x**: Prior versions populated `data.value` with the decimal-formatted amount when token metadata was available. As of EigenLayer-AVS 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`**.

**Breaking change relative to previous operator output**: Prior versions populated `data.value` with the decimal-formatted amount when token metadata was available. As of EigenLayer-AVS 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`**.

[Copilot]

The new comment states data.value is correct for ERC-20 transfer calldata, but the example still encodes it via Number(demoTriggerName.data.value). ERC-20 amounts are uint256 and can exceed JS safe-integer range, so Number(...) will silently lose precision and generate incorrect calldata. Use an integer-safe approach (e.g., BigInt-based) for hex encoding, and consider noting this constraint in the surrounding guidance.

Suggested change

	callData:
	"0xa9059cbb000000000000000000000000e0f7d11fd714674722d325cd86062a5f1882e13a{{ Number(demoTriggerName.data.value).toString(16).padStart(64, '0') }}",
	// Encode it with an integer-safe path (`BigInt`), because ERC-20 amounts can exceed
	// JavaScript's safe integer range and `Number(...)` would silently lose precision.
	callData:
	"0xa9059cbb000000000000000000000000e0f7d11fd714674722d325cd86062a5f1882e13a{{ BigInt(demoTriggerName.data.value).toString(16).padStart(64, '0') }}",