Cadence Codegen

A tool for analyzing Cadence smart contracts and generating code. It extracts transaction and script information, including parameters, imports, and return types.

Installation

Using npm (Recommended)

# Global installation
npm install -g @outblock/cadence-codegen

# Or use in a project
npm install @outblock/cadence-codegen
npx cadence-codegen --help

Using Homebrew

brew tap outblock/tap
brew install cadence-codegen

Update Homebrew

brew update && brew upgrade cadence-codegen

Using Go

go install github.com/outblock/cadence-codegen@latest

Usage

Analyze Cadence Files

Analyze Cadence files and generate a JSON report:

# Analyze a directory of Cadence files
cadence-codegen analyze ./contracts

# Analyze with custom output path
cadence-codegen analyze ./contracts output.json

# Analyze without base64 encoding
cadence-codegen analyze ./contracts --base64=false

Generate Swift Code

Generate Swift code from Cadence files or JSON:

# Generate from Cadence files (outputs to CadenceGen.swift)
cadence-codegen swift ./contracts

# Generate from Cadence files with custom output path
cadence-codegen swift ./contracts output.swift

# Generate from previously analyzed JSON
cadence-codegen swift analysis.json output.swift

Generate TypeScript Code

Generate TypeScript code from Cadence files or JSON:

# Generate from Cadence files (outputs to cadence.generated.ts)
cadence-codegen typescript ./contracts

# Generate from Cadence files with custom output path
cadence-codegen typescript ./contracts output.ts

# Generate from previously analyzed JSON
cadence-codegen typescript analysis.json output.ts

Generate Go Code

Generate Go code from Cadence files or JSON:

# Generate from Cadence files (outputs to cadence_generated.go)
cadence-codegen golang ./contracts

# Using the "go" alias
cadence-codegen go ./contracts

# Generate from Cadence files with custom output path
cadence-codegen golang ./contracts output.go

# Generate from previously analyzed JSON
cadence-codegen golang analysis.json output.go

Features

• Analyzes Cadence files (.cdc)
• Extracts:
  • Transaction parameters and types
  • Script parameters and return types
  • Import statements
  • Struct definitions
• Generates:
  • Structured JSON output
  • Swift code with type-safe wrappers
  • TypeScript code with FCL integration
  • Go code with typed structs and helper functions
• Supports folder-based tagging for better organization
• Base64 encoding of Cadence files (optional)

JSON Output Format

{
  "transactions": {
    "filename.cdc": {
      "fileName": "filename.cdc",
      "type": "transaction",
      "parameters": [
        {
          "name": "amount",
          "typeStr": "UFix64",
          "optional": false
        }
      ],
      "imports": [
        {
          "contract": "FungibleToken",
          "address": "0xFungibleToken"
        }
      ],
      "tag": "TokenTransfer"
    }
  },
  "scripts": {
    // Similar structure for scripts
  },
  "structs": {
    // Struct definitions
  }
}

Generated Swift Code

The generated Swift code includes:

• Type-safe enums for transactions and scripts
  • Separate enums for each folder (e.g., CadenceGen.EVM for files in the EVM folder)
  • Main CadenceGen enum for files in the root directory
• Struct definitions with proper Swift types
• Automatic Flow SDK integration
• Support for async/await
• Error handling

Example usage of generated Swift code:

// Execute a script from the EVM folder
let result: String? = try await flow.query(CadenceGen.EVM.getAddr(flowAddress: address))

// Execute a script from the root directory
let result: String? = try await flow.query(CadenceGen.getAddr(flowAddress: address))

// Send a transaction
let txId = try await flow.sendTx(
    CadenceGen.EVM.createCoa(amount: amount),
    singers: [signer]
) {
    // Transaction build options
}

Generated TypeScript Code

The generated TypeScript code includes:

• Type-safe functions for transactions and scripts
• FCL (Flow Client Library) integration
• Support for request and response interceptors
• Automatic type conversion from Cadence to TypeScript
• Support for async/await
• Struct definitions with proper TypeScript interfaces

Example usage of generated TypeScript code:

import { CadenceService } from "./cadence.generated";

const service = new CadenceService();

// Add interceptors for request/response processing
service.useRequestInterceptor((config) => {
  console.log("Request config:", config);
  return config;
});

service.useResponseInterceptor((config, response) => {
  console.log("Response:", response);
  return { config, response };
});

// Execute a script
const result = await service.getAddr(flowAddress);

// Send a transaction
const txId = await service.createCoa(amount);

Generated Go Code

The generated Go code includes:

• Typed Go structs from Cadence composite types (with JSON tags)
• Base64-encoded Cadence code constants with decoder functions
• Parameter structs for typed access to transaction/script arguments
• Cadence-to-Go type mapping (Int/UInt families to native Go types, Int128/Int256/UInt128/UInt256 to *big.Int, UFix64/Fix64/Address to string)
• Support for arrays, dictionaries, optionals, and nested types
• Tag-based grouping via comment sections

Example usage of generated Go code:

package main

import (
    "fmt"
    cadence "path/to/cadence_generated"
)

func main() {
    // Get the Cadence code for a transaction
    code := cadence.TransferTokensCode()
    fmt.Println(code)

    // Use typed parameter struct
    params := cadence.TransferTokensParams{
        Amount: "10.0",
        To:     "0x1234567890abcdef",
    }
    fmt.Printf("Transfer %s to %s\n", params.Amount, params.To)

    // Get the Cadence code for a script
    scriptCode := cadence.GetBalanceCode()
    fmt.Println(scriptCode)
}

NPM Integration

When installed via npm, the tool automatically downloads the appropriate binary for your platform (macOS, Linux, Windows) during installation. This provides a seamless experience for JavaScript/TypeScript developers who want to integrate Cadence code generation into their build processes.

Use in package.json scripts

{
  "scripts": {
    "codegen": "cadence-codegen typescript ./cadence output.ts",
    "build": "npm run codegen && tsc"
  }
}

Use programmatically

const { execSync } = require('child_process');

// Generate TypeScript code
execSync('cadence-codegen typescript ./contracts generated.ts');

// Or analyze contracts
const analysis = execSync('cadence-codegen analyze ./contracts', { encoding: 'utf8' });
console.log(JSON.parse(analysis));

License

MIT License