Update GraphQL Schema

Updates the SDK's GraphQL schema and related types from an API server instance.

Usage

/schema-update local    # Download from local server
/schema-update staging  # Download from staging server
/schema-update          # Will prompt for server choice

Checklist

You MUST use TodoWrite to create a todo for EACH step below. Mark each complete only after verification.

Download Schema

• Determine server source (from argument or ask user): local or staging
• Run schema download from packages/graphql:

- Local: pnpm gql:download:local - Staging: pnpm gql:download:staging

• Run pnpm gql:generate:introspection to generate GraphQL documents

Update Documents

• Cross-reference packages/graphql/schema.graphql with existing GQL documents
• Add missing fields to existing fragments
• Introduce new fragments if necessary
• If new queries or mutations exist in schema, ask user if they should be added

Check for New Enums

• Search for new enum definitions in packages/graphql/schema.graphql
• For each new enum:

- Add enum definition to packages/graphql/src/enums.ts with JSDoc comments - Import the enum type in packages/graphql/src/graphql.ts - Add scalar binding in graphql config (alphabetically ordered)

• Note: Do NOT create separate type exports for enums - the enum definition serves as both value and type

Export Input Types

• Check for new input types in schema
• Common types (used across multiple queries): export from packages/graphql/src/inputs.ts
• Query-specific types: colocate with corresponding query files (permits.ts, transactions.ts, swaps.ts, user.ts, reserve.ts, hub.ts, misc.ts)
• Use pattern: export type InputName = ReturnType<typeof graphql.scalar<'InputName'>>;
• Exclude fork-related input types unless explicitly needed
• Ensure scalar bindings exist in graphql.ts for all input types

Update URQL Cache Configuration

Update packages/client/src/cache.ts to handle new/removed types:

Keys Section

• Add new types with id field: Type the data parameter with the fragment type from @aave/graphql and return data.id.

``typescript NewTypeName: (data: NewTypeName) => data.id, ``

• Add ephemeral types (value objects without stable identity): Return null to disable normalization

``typescript NewValueObject: () => null, ``

• Remove deleted types: Remove any types that no longer exist in the schema
• When unsure: If you're uncertain whether it needs normalization, ask the user

Resolvers Section

Add field transformers for enhanced client-side types:

• DateTime fields: Transform to JavaScript Date objects

``typescript TypeName: { dateField: transformToDate, // for non-nullable DateTime nullableDateField: transformToNullableDate, // for nullable DateTime }, ``

• BigDecimal fields: Transform to BigDecimal class instances

``typescript TypeName: { decimalField: transformToBigDecimal, // for non-nullable BigDecimal nullableDecimalField: transformToNullableBigDecimal, // for nullable BigDecimal }, ``

• BigInt fields: Transform to native BigInt

``typescript TypeName: { bigIntField: transformToBigInt, }, ``

Common Patterns

• Activity types (*Activity) typically have timestamp: DateTime! → use transformToDate
• Types with createdAt: DateTime (nullable) → use transformToNullableDate
• Types with createdAt: DateTime! (non-nullable) → use transformToDate
• Health factor types have nullable BigDecimal fields → use transformToNullableBigDecimal

Update Wrapped-Native Transform Lists

When new object types are added to the schema, evaluate whether they belong in packages/client/src/displayTransform.ts:

• For each new object type, ask: does it represent a protocol reserve context (i.e. its Erc20Token descendants are reserve assets like WETH that should display as ETH)?

- If yes → add to WRAPPEDNATIVETRANSFORM_ALLOWLIST

• Does it represent a user wallet balance or reward payout that could appear nested inside a reserve context but should NOT be transformed?

- If yes → add to WRAPPEDNATIVETRANSFORM_BLOCKLIST

• If uncertain, ask the user — don't silently skip

Note: Types in neither list are transparent — they inherit the transform context from their parent. Only add a type when it needs to change the context (turn it on or off).

Validate

IMPORTANT: Do not mark the schema update complete until build and all tests pass.

• Run pnpm check from packages/graphql to verify document integrity
• Run pnpm build to ensure TypeScript compilation succeeds

- If build fails, fix the errors and re-run pnpm build - Repeat until build succeeds with zero errors

• Run pnpm test --run to verify tests pass

- If tests fail, analyze failures, fix the code, and re-run tests - If the fix was in a sub-package compared to where the tests failed, re-run pnpm build first - Repeat until all tests pass

• Run pnpm lint:fix to format code
• Confirm both build and tests pass before marking complete

Code Patterns

Enum Definition (enums.ts)

/**
 * Description of what this enum represents.
 */
export enum EnumName {
  /**
   * Description of this value
   */
  VALUE_ONE = 'VALUE_ONE',
  /**
   * Description of this value
   */
  VALUE_TWO = 'VALUE_TWO',
}

Scalar Binding (graphql.ts)

// Add to imports
import type { ..., EnumName } from './enums';

// Add to scalars config (alphabetically)
scalars: {
  ...
  EnumName: EnumName,
  ...
}

Input Type Export

export type InputName = ReturnType<typeof graphql.scalar<'InputName'>>;

Stop Conditions

Never mark the schema update as complete while build errors or test failures exist. The iterative fix-and-verify loop is mandatory.

Common Mistakes

1. Creating type exports for enums - Enums are both values and types; don't use ReturnType<typeof graphql.scalar<'EnumName'>>
2. Adding new queries/mutations without being asked - Only update existing documents unless explicitly requested
3. Forgetting scalar bindings - Every input type needs a corresponding entry in graphql.ts
4. Non-alphabetical ordering - Scalar bindings should be alphabetically ordered
5. Missing JSDoc comments - All enums should have documentation
6. Forgetting cache.ts updates - New types need keys configuration; types with DateTime/BigDecimal/BigInt need resolvers
7. Wrong nullable transformer - Use transformToNullableDate/transformToNullableBigDecimal for nullable fields, non-nullable variants for required fields
8. Missing type imports in cache.ts - Add imports for any new types used in the keys section
9. Marking complete with failing build/tests - Always run pnpm build and pnpm test --run and fix all errors before marking complete
10. Skipping the wrapped-native transform evaluation - Every new object type must be checked against WRAPPEDNATIVETRANSFORMALLOWLIST / WRAPPEDNATIVETRANSFORMBLOCKLIST in displayTransform.ts; silently omitting it can cause wrong token display