@subsquid/evm-typegen 4.6.0 → 5.0.0

package/src/description.ts

@@ -0,0 +1,221 @@
+import {keccak256} from '@subsquid/evm-abi'
+import type {Abi, AbiEvent, AbiFunction, AbiParameter} from 'abitype'
+
+export interface ContractDef {
+    events: EventDef[]
+    functions: FunctionDef[]
+}
+
+export interface DocDef {
+    notice?: string
+    dev?: string
+    params?: Record<string, string>
+    returns?: Record<string, string>
+}
+
+/** NatSpec documentation extracted from a compilation artifact's userdoc/devdoc fields. */
+export interface NatSpec {
+    userdoc?: {
+        methods?: Record<string, {notice?: string}>
+        events?: Record<string, {notice?: string}>
+    }
+    devdoc?: {
+        methods?: Record<string, {details?: string; params?: Record<string, string>; returns?: Record<string, string>}>
+        events?: Record<string, {details?: string; params?: Record<string, string>}>
+    }
+}
+
+export interface EventDef {
+    name: string
+    signature: string
+    topic: string
+    inputs: FieldDef[]
+    key: string
+    typeName: string
+    docs?: DocDef
+}
+
+export interface FunctionDef {
+    name: string
+    signature: string
+    selector: string
+    inputs: FieldDef[]
+    outputs: FieldDef[]
+    key: string
+    paramsTypeName: string
+    returnTypeName: string
+    docs?: DocDef
+}
+
+export interface FieldDef {
+    name: string
+    type: TypeDef
+    indexed?: boolean
+    doc?: string
+}
+
+export type TypeDef =
+    | {kind: 'primitive'; name: string}
+    | {kind: 'array'; item: TypeDef}
+    | {kind: 'fixedArray'; item: TypeDef; size: number}
+    | {kind: 'tuple'; fields: FieldDef[]}
+
+export function describe(abi: Abi, natspec?: NatSpec): ContractDef {
+    const rawEvents = abi.filter((x) => x.type === 'event') as AbiEvent[]
+    const rawFunctions = abi.filter((x) => x.type === 'function') as AbiFunction[]
+
+    const eventSuffix = overloadSuffixer(rawEvents)
+    const functionSuffix = overloadSuffixer(rawFunctions)
+
+    const events: EventDef[] = rawEvents.map((e) => {
+        const signature = eventSignature(e)
+        const docs = buildEventDocs(signature, natspec)
+        const inputs = e.inputs.map((p, i) => toFieldDef(p, i, true))
+        annotateParamDocs(inputs, docs?.params)
+        return {
+            name: e.name,
+            signature,
+            topic: `0x${keccak256(signature).toString('hex')}`,
+            inputs,
+            key: eventSuffix(e, e.name),
+            typeName: eventSuffix(e, `${capitalize(e.name)}EventArgs`),
+            docs,
+        }
+    })
+
+    const functions: FunctionDef[] = rawFunctions.map((f) => {
+        const signature = fnSignature(f)
+        const docs = buildFunctionDocs(signature, natspec)
+        const inputs = f.inputs.map((p, i) => toFieldDef(p, i, false))
+        const outputs = (f.outputs ?? []).map((p, i) => toFieldDef(p, i, false))
+        annotateParamDocs(inputs, docs?.params)
+        annotateReturnDocs(outputs, docs?.returns)
+        return {
+            name: f.name,
+            signature,
+            selector: `0x${keccak256(signature).slice(0, 4).toString('hex')}`,
+            inputs,
+            outputs,
+            key: functionSuffix(f, f.name),
+            paramsTypeName: functionSuffix(f, `${capitalize(f.name)}Params`),
+            returnTypeName: functionSuffix(f, `${capitalize(f.name)}Return`),
+            docs,
+        }
+    })
+
+    return {events, functions}
+}
+
+function buildEventDocs(signature: string, natspec: NatSpec | undefined): DocDef | undefined {
+    const notice = natspec?.userdoc?.events?.[signature]?.notice
+    const devEntry = natspec?.devdoc?.events?.[signature]
+    if (!notice && !devEntry) return undefined
+    return filterEmptyDoc({
+        notice,
+        dev: devEntry?.details,
+        params: devEntry?.params,
+    })
+}
+
+function buildFunctionDocs(signature: string, natspec: NatSpec | undefined): DocDef | undefined {
+    const notice = natspec?.userdoc?.methods?.[signature]?.notice
+    const devEntry = natspec?.devdoc?.methods?.[signature]
+    if (!notice && !devEntry) return undefined
+    return filterEmptyDoc({
+        notice,
+        dev: devEntry?.details,
+        params: devEntry?.params,
+        returns: devEntry?.returns,
+    })
+}
+
+function filterEmptyDoc(doc: DocDef): DocDef | undefined {
+    const hasContent =
+        doc.notice != null ||
+        doc.dev != null ||
+        (doc.params != null && Object.keys(doc.params).length > 0) ||
+        (doc.returns != null && Object.keys(doc.returns).length > 0)
+    return hasContent ? doc : undefined
+}
+
+function annotateParamDocs(fields: FieldDef[], params: Record<string, string> | undefined): void {
+    if (!params) return
+    for (const field of fields) {
+        const doc = params[field.name]
+        if (doc) field.doc = doc
+    }
+}
+
+function annotateReturnDocs(fields: FieldDef[], returns: Record<string, string> | undefined): void {
+    if (!returns) return
+    for (let i = 0; i < fields.length; i++) {
+        const field = fields[i]
+        const doc = returns[field.name] ?? returns[`_${i}`]
+        if (doc) field.doc = doc
+    }
+}
+
+function overloadSuffixer(items: readonly (AbiEvent | AbiFunction)[]) {
+    const counts = new Map<string, number>()
+    const indices = new Map<AbiEvent | AbiFunction, number>()
+    for (const item of items) {
+        const seen = counts.get(item.name) ?? 0
+        indices.set(item, seen)
+        counts.set(item.name, seen + 1)
+    }
+    return (item: AbiEvent | AbiFunction, base: string): string => {
+        if ((counts.get(item.name) ?? 1) <= 1) return base
+        const idx = indices.get(item)!
+        return idx === 0 ? base : `${base}_${idx}`
+    }
+}
+
+function toFieldDef(p: AbiParameter, index: number, isEventInput: boolean): FieldDef {
+    const field: FieldDef = {
+        name: p.name || `_${index}`,
+        type: toTypeDef(p),
+    }
+    if (isEventInput && (p as any).indexed) field.indexed = true
+    return field
+}
+
+function toTypeDef(p: AbiParameter): TypeDef {
+    const fixed = p.type.match(/\[(\d+)\]$/)
+    if (fixed) {
+        return {kind: 'fixedArray', size: Number(fixed[1]), item: toTypeDef(stripOuterArray(p))}
+    }
+    if (p.type.endsWith('[]')) {
+        return {kind: 'array', item: toTypeDef(stripOuterArray(p))}
+    }
+    if (p.type.startsWith('tuple')) {
+        const components = ((p as any).components || []) as AbiParameter[]
+        return {
+            kind: 'tuple',
+            fields: components.map((c, i) => toFieldDef(c, i, false)),
+        }
+    }
+    return {kind: 'primitive', name: p.type}
+}
+
+function stripOuterArray(p: AbiParameter): AbiParameter {
+    return {...(p as any), type: p.type.replace(/\[\d*\]$/, '')} as AbiParameter
+}
+
+export function canonicalType(p: AbiParameter): string {
+    if (!p.type.startsWith('tuple')) return p.type
+    const arrayBrackets = p.type.slice(5)
+    const components = (p as any).components as AbiParameter[]
+    return `(${components.map(canonicalType).join(',')})${arrayBrackets}`
+}
+
+function eventSignature(e: AbiEvent): string {
+    return `${e.name}(${e.inputs.map(canonicalType).join(',')})`
+}
+
+function fnSignature(f: AbiFunction): string {
+    return `${f.name}(${f.inputs.map(canonicalType).join(',')})`
+}
+
+function capitalize(s: string): string {
+    return s.charAt(0).toUpperCase() + s.slice(1)
+}

package/src/main.ts

@@ -1,12 +1,13 @@
-import * as fs from 'fs'
-import path from 'path'
-import { InvalidArgumentError, InvalidOptionArgumentError, program } from 'commander'
-import { createLogger } from '@subsquid/logger'
-import { runProgram, wait } from '@subsquid/util-internal'
+import * as fs from 'node:fs'
+import path from 'node:path'
+import {InvalidArgumentError, InvalidOptionArgumentError, program} from 'commander'
+import {createLogger} from '@subsquid/logger'
+import {runProgram, wait} from '@subsquid/util-internal'
 import * as validator from '@subsquid/util-internal-commander'
-import { Typegen } from './typegen'
-import { GET } from './util/fetch'
-import { OutDir } from '@subsquid/util-internal-code-printer'
+import {Typegen} from './typegen'
+import type {NatSpec} from './description'
+import {GET} from './util/fetch'
+import {OutDir} from '@subsquid/util-internal-code-printer'
 import {chainIdOption} from './chainIds'
 
 const LOG = createLogger('sqd:evm-typegen')
@@ -14,40 +15,40 @@ const PROXY_ETHERSCAN = 'https://cloud.sqd.dev/chains/api/v1/evm/abi'
 const ORIGIN_ETHERSCAN = 'https://api.etherscan.io/v2/api'
 
 runProgram(
-  async function () {
-    program
-      .description(
-        `
+    async function () {
+        program
+            .description(
+                `
 Generates TypeScript facades for EVM transactions, logs and eth_call queries.
 
 The generated facades are assumed to be used by "squids" indexing EVM data.
     `.trim(),
-      )
-      .name('squid-evm-typegen')
-      .argument('<output-dir>', 'output directory for generated definitions')
-      .argument('[abi...]', 'ABI file', specArgument)
-      .option('--multicall', 'generate facade for MakerDAO multicall contract')
-      .option(
-        '--etherscan-api <url>',
-        'etherscan API to fetch contract ABI by a known address\n(if no API token is provided, the default value equals to SQD Proxy service, otherwise equals to Etherscan API)', 
-        validator.Url(['http:', 'https:']),
-      )
-      .option('--etherscan-api-key <key>', 'etherscan API key')
-      .option(
-        '--chain-id <id>',
-        'chain ID (numeric or named, e.g., "1" or "ethereum") to fetch the contract from',
-        chainIdOption,
-        1,
-      )
-      .option(
-        '--etherscan-chain-id <id>',
-        'DEPRECATED: use --chain-id instead. Chain ID (numeric or named, e.g., "1" or "ethereum") to fetch the contract from',
-        chainIdOption,
-      )
-      .option('--clean', 'delete output directory before run')
-      .addHelpText(
-        'afterAll',
-        `
+            )
+            .name('squid-evm-typegen')
+            .argument('<output-dir>', 'output directory for generated definitions')
+            .argument('[abi...]', 'ABI file', specArgument)
+            .option('--multicall', 'generate facade for MakerDAO multicall contract')
+            .option(
+                '--etherscan-api <url>',
+                'etherscan API to fetch contract ABI by a known address\n(if no API token is provided, the default value equals to SQD Proxy service, otherwise equals to Etherscan API)',
+                validator.Url(['http:', 'https:']),
+            )
+            .option('--etherscan-api-key <key>', 'etherscan API key')
+            .option(
+                '--chain-id <id>',
+                'chain ID (numeric or named, e.g., "1" or "ethereum") to fetch the contract from',
+                chainIdOption,
+                1,
+            )
+            .option(
+                '--etherscan-chain-id <id>',
+                'DEPRECATED: use --chain-id instead. Chain ID (numeric or named, e.g., "1" or "ethereum") to fetch the contract from',
+                chainIdOption,
+            )
+            .option('--clean', 'delete output directory before run')
+            .addHelpText(
+                'afterAll',
+                `
 ABI file can be specified in three ways:
 
 1. as a plain JSON file:
@@ -67,186 +68,186 @@ You can overwrite basename of generated files using fragment (#) suffix.
 
 squid-evm-typegen src/abi 0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413#contract   
         `,
-      )
-
-    program.parse()
+            )
+
+        program.parse()
+
+        let opts = program.opts() as {
+            clean?: boolean
+            multicall?: boolean
+            etherscanApi?: string
+            etherscanApiKey?: string
+            chainId?: number
+            etherscanChainId?: number
+        }
+        let dest = new OutDir(program.processedArgs[0])
+        let specs = program.processedArgs[1] as Spec[]
+
+        if (opts.etherscanChainId) {
+            LOG.warn('Option --etherscan-chain-id is deprecated. Please use --chain-id instead')
+            if (opts.chainId) {
+                throw new InvalidOptionArgumentError(
+                    'Option --chain-id and --etherscan-chain-id cannot be used together',
+                )
+            }
+            opts.chainId = opts.etherscanChainId
+            opts.etherscanChainId = undefined
+        }
+
+        if (opts.clean && dest.exists()) {
+            LOG.info(`deleting ${dest.path()}`)
+            dest.del()
+        }
+
+        if (specs.length == 0 && !opts.multicall) {
+            LOG.warn('no ABI files given, nothing to generate')
+            return
+        }
+
+        if (opts.multicall) {
+            dest.add('multicall.ts', [__dirname, '../src/multicall.ts'])
+            LOG.info(`saved ${dest.path('multicall.ts')}`)
+        }
+
+        if (specs.length > 0) {
+            dest.add('abi.support.ts', [__dirname, '../src/abi.support.ts'])
+            LOG.info(`saved ${dest.path('abi.support.ts')}`)
+        }
+
+        for (let spec of specs) {
+            LOG.info(`processing ${spec.src}`)
+            let {abi, natspec} = await read(spec, opts)
+            await new Typegen(dest, abi, spec.name, LOG, natspec).generate()
+        }
+    },
+    (err) => LOG.fatal(err),
+)
 
-    let opts = program.opts() as {
-      clean?: boolean
-      multicall?: boolean
-      etherscanApi?: string
-      etherscanApiKey?: string
-      chainId?: number
-      etherscanChainId?: number
+async function read(
+    spec: Spec,
+    options: {
+        etherscanApi?: string
+        chainId?: number
+        etherscanApiKey?: string
+    },
+): Promise<{abi: any; natspec?: NatSpec}> {
+    if (spec.kind == 'address') {
+        return {abi: await fetchFromEtherscan(spec.src, getEtherscanAPIConfig(options))}
     }
-    let dest = new OutDir(program.processedArgs[0])
-    let specs = program.processedArgs[1] as Spec[]
-
-    if (opts.etherscanChainId) { 
-      LOG.warn('Option --etherscan-chain-id is deprecated. Please use --chain-id instead')
-      if (opts.chainId) {
-        throw new InvalidOptionArgumentError('Option --chain-id and --etherscan-chain-id cannot be used together')
-      }
-      opts.chainId = opts.etherscanChainId
-      delete opts.etherscanChainId
+    let raw: any
+    if (spec.kind == 'url') {
+        raw = await GET(spec.src)
+    } else {
+        raw = JSON.parse(fs.readFileSync(spec.src, 'utf-8'))
     }
-
-    if (opts.clean && dest.exists()) {
-      LOG.info(`deleting ${dest.path()}`)
-      dest.del()
+    if (Array.isArray(raw)) {
+        return {abi: raw}
     }
-
-    if (specs.length == 0 && !opts.multicall) {
-      LOG.warn('no ABI files given, nothing to generate')
-      return
+    if (Array.isArray(raw?.abi)) {
+        return {abi: raw.abi, natspec: extractNatSpec(raw)}
     }
+    throw new Error('Unrecognized ABI format')
+}
 
-    if (opts.multicall) {
-      dest.add('multicall.ts', [__dirname, '../src/multicall.ts'])
-      LOG.info(`saved ${dest.path('multicall.ts')}`)
-    }
+function extractNatSpec(artifact: any): NatSpec | undefined {
+    const userdoc = artifact.userdoc
+    const devdoc = artifact.devdoc
+    if (!userdoc && !devdoc) return undefined
+    return {userdoc, devdoc}
+}
 
-    for (let spec of specs) {
-      LOG.info(`processing ${spec.src}`)
-      let abi_json = await read(spec, opts)
-      await new Typegen(dest, abi_json, spec.name, LOG).generate()
-    }
-  },
-  (err) => LOG.fatal(err),
-)
+async function fetchFromEtherscan(address: string, config: EtherscanAPIConfig): Promise<any> {
+    let url = new URL(config.api)
 
-async function read(
-  spec: Spec,
-  options: {
-    etherscanApi?: string;
-    chainId?: number
-    etherscanApiKey?: string,
-  },
-): Promise<any> {
-  if (spec.kind == 'address') {
-    return fetchFromEtherscan(spec.src, getEtherscanAPIConfig(options))
-  }
-  let abi: any
-  if (spec.kind == 'url') {
-    abi = await GET(spec.src)
-  } else {
-    abi = JSON.parse(fs.readFileSync(spec.src, 'utf-8'))
-  }
-  if (Array.isArray(abi)) {
-    return abi
-  } else if (Array.isArray(abi?.abi)) {
-    return abi.abi
-  } else {
-    throw new Error('Unrecognized ABI format')
-  }
-}
+    let params = new URLSearchParams({
+        module: 'contract',
+        action: 'getabi',
+        address,
+        chainid: config.chainId.toString(),
+    })
 
-async function fetchFromEtherscan(
-  address: string,
-  config: EtherscanAPIConfig,
-): Promise<any> {
-  let url = new URL(config.api)
-
-  let params = new URLSearchParams({
-    module: 'contract',
-    action: 'getabi',
-    address,
-    chainid: config.chainId.toString(),
-  })
-
-  if (config.apiKey) {
-    params.set('apiKey', config.apiKey);
-  }
-
-  url.search = params.toString()
-
-  let response: { status: string; result: string }
-  let attempts = 0
-  while (true) {
-    response = await GET(url.toString())
-    if (
-      response.status == '0' &&
-      response.result.includes('rate limit') &&
-      attempts < 4
-    ) {
-      attempts += 1
-      let timeout = attempts * 2
-      LOG.warn(
-        `faced rate limit error while trying to fetch contract ABI. Trying again in ${timeout} seconds.`,
-      )
-      await wait(timeout * 1000)
-    } else {
-      break
+    if (config.apiKey) {
+        params.set('apiKey', config.apiKey)
     }
-  }
-  if (response.status == '1') {
-    return JSON.parse(response.result)
-  } else {
-    throw new Error(
-      `Failed to fetch contract ABI from ${config.api}: ${response.result}`,
-    )
-  }
+
+    url.search = params.toString()
+
+    let response: {status: string; result: string}
+    let attempts = 0
+    while (true) {
+        response = await GET(url.toString())
+        if (response.status == '0' && response.result.includes('rate limit') && attempts < 4) {
+            attempts += 1
+            let timeout = attempts * 2
+            LOG.warn(`faced rate limit error while trying to fetch contract ABI. Trying again in ${timeout} seconds.`)
+            await wait(timeout * 1000)
+        } else {
+            break
+        }
+    }
+    if (response.status == '1') {
+        return JSON.parse(response.result)
+    }
+    throw new Error(`Failed to fetch contract ABI from ${config.api}: ${response.result}`)
 }
 
 interface Spec {
-  kind: 'address' | 'url' | 'file'
-  src: string
-  name: string
+    kind: 'address' | 'url' | 'file'
+    src: string
+    name: string
 }
 
 function specArgument(value: string, prev?: Spec[]): Spec[] {
-  let spec = parseSpec(value)
-  prev = prev || []
-  prev.push(spec)
-  return prev
+    let spec = parseSpec(value)
+    prev = prev || []
+    prev.push(spec)
+    return prev
 }
 
 function isAddress(spec: string): boolean {
-  return spec.match(/^0x[0-9a-fA-F]{40}$/) !== null
+    return spec.match(/^0x[0-9a-fA-F]{40}$/) !== null
 }
 
 function parseSpec(spec: string): Spec {
-  let [src, fragment] = splitFragment(spec)
-  if (src.startsWith('0x')) {
-    if (!isAddress(src))
-      throw new InvalidArgumentError('Invalid contract address')
-    return {
-      kind: 'address',
-      src,
-      name: fragment || src,
+    let [src, fragment] = splitFragment(spec)
+    if (src.startsWith('0x')) {
+        if (!isAddress(src)) throw new InvalidArgumentError('Invalid contract address')
+        return {
+            kind: 'address',
+            src,
+            name: fragment || src,
+        }
     }
-  } else if (src.includes('://')) {
-    let u = new URL(validator.Url(['http:', 'https:'])(src))
-    return {
-      kind: 'url',
-      src,
-      name: fragment || basename(u.pathname),
+    if (src.includes('://')) {
+        let u = new URL(validator.Url(['http:', 'https:'])(src))
+        return {
+            kind: 'url',
+            src,
+            name: fragment || basename(u.pathname),
+        }
     }
-  } else {
     return {
-      kind: 'file',
-      src,
-      name: fragment || basename(src),
+        kind: 'file',
+        src,
+        name: fragment || basename(src),
     }
-  }
 }
 
 function splitFragment(spec: string): [string, string] {
-  let parts = spec.split('#')
-  if (parts.length > 1) {
-    let fragment = parts.pop()!
-    return [parts.join('#'), fragment]
-  } else {
+    let parts = spec.split('#')
+    if (parts.length > 1) {
+        let fragment = parts.pop()!
+        return [parts.join('#'), fragment]
+    }
     return [spec, '']
-  }
 }
 
 function basename(file: string): string {
-  let name = path.parse(file).name
-  if (name) return name
-  throw new InvalidArgumentError(
-    `Can't derive target basename for output files. Use url fragment to specify it, e.g. #erc20`,
-  )
+    let name = path.parse(file).name
+    if (name) return name
+    throw new InvalidArgumentError(
+        `Can't derive target basename for output files. Use url fragment to specify it, e.g. #erc20`,
+    )
 }
 
 interface EtherscanAPIConfig {
@@ -262,11 +263,11 @@ function getEtherscanAPIConfig(options: {
 }): EtherscanAPIConfig {
     let api: string
     if (options.etherscanApi != null) {
-      api = normalizeEtherscanAPIUrl(options.etherscanApi)
-    }  else if (options.etherscanApiKey != null) {
-      api = ORIGIN_ETHERSCAN
+        api = normalizeEtherscanAPIUrl(options.etherscanApi)
+    } else if (options.etherscanApiKey != null) {
+        api = ORIGIN_ETHERSCAN
     } else {
-      api = PROXY_ETHERSCAN
+        api = PROXY_ETHERSCAN
     }
 
     return {
@@ -277,9 +278,9 @@ function getEtherscanAPIConfig(options: {
 }
 
 function normalizeEtherscanAPIUrl(url: string) {
-  if (url.endsWith('/api')) {
-    return url
-  }
+    if (url.endsWith('/api')) {
+        return url
+    }
 
-  return url.endsWith('/') ? url + 'api' : url + '/api'
-}
+    return url.endsWith('/') ? `${url}api` : `${url}/api`
+}