JSON to TypeScript ABI Converter

Purpose

Automates the conversion of JSON ABI files to TypeScript files with properly typed

const

exports, ensuring type safety and consistency across the SDK.

When to Use

• Adding new contract ABIs to the SDK
• Updating existing ABI files after contract changes
• Batch converting multiple ABI files
• Ensuring ABI TypeScript files match their JSON sources

How It Works

The skill provides a conversion script that:

1. Reads JSON ABI file(s) from

   src/evm/abi/

2. Generates TypeScript files in

   src/evm/releases/

   with:
   • Named export using camelCase convention

   • as const

     assertion for full type inference
   • Preserved JSON structure
3. Automatically runs Biome formatting on generated files

Usage

Single File Conversion

bun .claude/skills/abi-codegen/scripts/codegen.ts src/evm/abi/lockup/v3.0/SablierLockup.json

Multiple Files (Glob Pattern)

bun .claude/skills/abi-codegen/scripts/codegen.ts "src/evm/abi/lockup/v3.0/*.json"

All ABIs in Directory

bun .claude/skills/abi-codegen/scripts/codegen.ts "src/evm/abi/**/*.json"

File Path Conventions

Input Path Pattern

src/evm/abi/{protocol}/{version}/{ContractName}.json

Output Path Pattern

src/evm/releases/{protocol}/{version}/abi/{ContractName}.ts

Naming Convention

• JSON file:

  SablierLockup.json

• TS export:

  sablierLockupAbi

• Pattern: PascalCase filename → camelCase + "Abi" suffix

Examples

Example 1: Convert Lockup ABI

Input:

src/evm/abi/lockup/v3.0/SablierLockup.json

[
  {
    "inputs": [
      { "internalType": "address", "name": "to", "type": "address" },
      { "internalType": "uint256", "name": "tokenId", "type": "uint256" }
    ],
    "name": "approve",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  }
]

Command:

bun .claude/skills/abi-codegen/scripts/codegen.ts src/evm/abi/lockup/v3.0/SablierLockup.json

Output:

src/evm/releases/lockup/v3.0/abi/SablierLockup.ts

export const sablierLockupAbi = [
  {
    inputs: [
      { internalType: "address", name: "to", type: "address" },
      { internalType: "uint256", name: "tokenId", type: "uint256" },
    ],
    name: "approve",
    outputs: [],
    stateMutability: "nonpayable",
    type: "function",
  },
] as const;

Example 2: Batch Convert All v3.0 Lockup ABIs

bun .claude/skills/abi-codegen/scripts/codegen.ts "src/evm/abi/lockup/v3.0/*.json"

Output:

✓ Converted: SablierLockup.json → SablierLockup.ts
✓ Converted: SablierLockupDynamic.json → SablierLockupDynamic.ts
✓ Converted: SablierLockupLinear.json → SablierLockupLinear.ts
✓ Converted: SablierLockupTranched.json → SablierLockupTranched.ts

Running Biome formatter...
✓ Formatted 4 files

Done! Converted 4 ABI files.

Script Details

Input Processing

• Accepts absolute or relative file paths
• Supports glob patterns via Bun's

  Glob

  API
• Validates JSON structure before conversion
• Handles missing or malformed files gracefully

Output Generation

• Creates necessary directories automatically
• Preserves JSON structure exactly (no data loss)
• Applies consistent naming convention
• Adds

  as const

  for maximum type inference

Post-Processing

• Runs

  just biome-write

  on all generated TypeScript files
• Ensures consistent formatting with project standards
• Reports any formatting errors

Error Handling

The script handles common errors:

• File not found: Clear error message with file path
• Invalid JSON: Shows parsing error with line/column
• Write permission: Reports directory/file permission issues
• Biome errors: Displays formatting failures (non-fatal)

Troubleshooting

Script Not Found

# Ensure you're in the project root
pwd  # Should show .../sablier/sdk

# Verify script exists
ls .claude/skills/abi-codegen/scripts/codegen.ts

Invalid JSON

# Validate JSON before converting
jq . src/evm/abi/lockup/v3.0/SablierLockup.json

TypeScript Errors After Conversion

# Run type check to verify
just tsc-check

# If errors occur, check:
# 1. Is the JSON structure valid for an ABI?
# 2. Are all required fields present?
# 3. Run Biome again: just biome-write

Glob Pattern Not Working

# Use quotes around glob patterns
bun .claude/skills/abi-codegen/scripts/codegen.ts "src/evm/abi/**/*.json"
#                                                 ^                    ^
#                                                 Quotes are required

Integration with Workflow

After Adding New ABIs

1. Place JSON ABI in

   src/evm/abi/{protocol}/{version}/

2. Run conversion script
3. Verify output in

   src/evm/releases/{protocol}/{version}/abi/

4. Run

   just tsc-check

   to verify types
5. Export from appropriate index file
6. Run

   just test

   to ensure no regressions

Before Committing ABI Changes

# Convert all modified ABIs
bun .claude/skills/abi-codegen/scripts/codegen.ts "src/evm/abi/**/*.json"

# Verify TypeScript
just tsc-check

# Run tests
just test

# Commit both JSON and generated TS files
git add src/evm/abi/ src/evm/releases/
git commit -m "feat: update ABIs for {protocol} {version}"

Technical Notes

Why

as const

?

The

as const

assertion provides:

• Literal types: String values become literal types (e.g.,

  "function"

  not

  string

  )
• Readonly arrays: Prevents accidental mutations
• Better inference: Viem uses literal types for better type checking
• Autocomplete: IDEs provide better suggestions

Why Separate JSON and TS?

• Source of truth: JSON files are copied from Foundry artifacts
• Version control: Easy to see diffs in JSON changes
• Type safety: TypeScript provides compile-time checks
• Build optimization: TypeScript files can be tree-shaken

Performance

• Typical conversion: <100ms per file
• Batch processing: ~500ms for 10 files
• Biome formatting: ~1-2s for all files
• Total overhead: Minimal, suitable for pre-commit hooks

Related Files

• Script:

  .claude/skills/abi-codegen/scripts/codegen.ts

• Source ABIs:

  src/evm/abi/{protocol}/{version}/*.json

• Output ABIs:

  src/evm/releases/{protocol}/{version}/abi/*.ts

• Build config:

  tsconfig.build.json

  (includes ABI copy step)

Future Enhancements

Potential improvements:

• Watch mode for automatic conversion on JSON changes
• Validation against official ABI schema
• Diff detection to only convert changed files
• Integration with Foundry broadcast parsing
• Automatic export statement generation in index files