solidity-ast

What is solidity-ast?

The solidity-ast package is a tool for parsing and analyzing the Abstract Syntax Tree (AST) of Solidity smart contracts. It provides utilities to traverse and manipulate the AST, which is useful for developers working on Solidity code analysis, refactoring, or tooling.

What are solidity-ast's main functionalities?

Parsing Solidity Source Code

This feature allows you to parse Solidity source code into an Abstract Syntax Tree (AST). The code sample demonstrates how to use the `parse` function to convert a Solidity contract into its AST representation.

const { parse } = require('solidity-ast');
const sourceCode = 'contract MyContract { function myFunction() public {} }';
const ast = parse(sourceCode);

Traversing the AST

This feature provides utilities to traverse the AST. The code sample shows how to use the `findAll` utility to find all function definitions within the AST and log their names.

const { findAll } = require('solidity-ast/utils');
const functions = findAll('FunctionDefinition', ast);
for (const func of functions) {
  console.log(func.name);
}

Other packages similar to solidity-ast

solidity-parser-antlr

solidity-parser-antlr is another package for parsing Solidity code into an AST. It uses ANTLR to generate the parser and provides a similar functionality to solidity-ast. However, solidity-parser-antlr is more focused on parsing and less on AST manipulation and traversal utilities.

solc

solc is the official Solidity compiler which also provides an AST output. While solc is primarily used for compiling Solidity code, it can also be used to generate an AST, but it lacks the dedicated traversal and manipulation utilities that solidity-ast offers.

README

Solidity AST Types

TypeScript types and a JSON Schema for the Solidity AST.

npm install solidity-ast

import type { SourceUnit, ContractDefinition } from 'solidity-ast';

The types included in the NPM package are automatically generated from the JSON Schema, so you will not find them in the repository. You can see what they look like on unpkg or the documentation.

Solidity Versioning

The types are currently accurate and tested for Solidity >=0.6.6, but you can very likely use them safely for any version since 0.6.0. For simple traversals they will probably work well for 0.5.0 and up as well.

The versioning story will be gradually improved upon and the ultimate goal is to be able to manipulate and traverse the AST in a uniform way that is as agnostic to the Solidity version as possible.

Utilities

Included in the package is a set of utility functions for type-safe interactions with nodes based on the node type.

isNodeType(nodeType, node)

A type predicate that can be used for narrowing the type of an unknown node, or combined with higher order functions like filter.

An array of node types can be used as well to check if the node matches one of them.

import { isNodeType } from 'solidity-ast/utils';

if (isNodeType('ContractDefinition', node)) {
  // node: ContractDefinition
}

const contractDefs = sourceUnit.nodes.filter(isNodeType('ContractDefinition'));
  // contractDefs: ContractDefinition[]

findAll(nodeType, node[, prune])

findAll is a generator function that will recursively enumerate all descendent nodes of a given node type. It does this in an efficient way by visiting only the nodes that are necessary for the searched node type.

import { findAll } from 'solidity-ast/utils';

for (const functionDef of findAll('FunctionDefinition', sourceUnit)) {
  // functionDef: FunctionDefinition
}

If the optional prune: (node: Node) => boolean argument is specified, findAll will apply the function to each node, if the return value is truthy the node will be ignored, neither yielding the node nor recursing into it. Note that prune is not available when curried.

To enumerate multiple node types at the same time, nodeType can be an array of node types such as ['EnumDefinition', 'StructDefinition'].

for (const typeDef of findAll(['EnumDefinition', 'StructDefinition'], sourceUnit)) {
  // typeDef: EnumDefinition | StructDefinition
}

To enumerate all subnodes regardless of node type, nodeType can be '*' (a string with a single asterisk).

astDereferencer(solcOutput) => (nodeType, id) => Node

astDereferencer looks up AST nodes based on their id. Notably, it works across multiple source files, which is why it needs the entire solc JSON output with the ASTs for all source files in a compilation.

On Hardhat, the solc JSON output can be found in build info files.

const deref = astDereferencer(solcOutput);

deref('ContractDefinition', 4);

for (const contractDef of findAll('ContractDefinition', sourceUnit)) {
  const baseContracts = contractDef.linearizedBaseContracts.map(deref('ContractDefinition'));
  ...
}

It is also possible to obtain the source unit that contains the dereferenced node:

const deref = astDereferencer(solcOutput);

const { node, sourceUnit } = deref.withSourceUnit('ContractDefinition', 4);

If the node type is unknown you can specify '*' for nodeType.

srcDecoder(solcInput, solcOutput, basePath = '.') => (node: Node) => string

srcDecoder allows decoding of the src property of a node, which looks something like 123:4:0, into a human-readable description of the location of that node, such as file.sol:10.

On Hardhat, the solc JSON input and output can be found in build info files.

const decodeSrc = srcDecoder(solcInput, solcOutput);
...
const location = decodeSrc(contractDefinition);
console.log('found contract at ' + location);

Changelog

0.4.57 (2024-07-16)

• Fixed ModifierDefinition.body: made nullable to support Solidity 0.6.7 virtual modifiers with empty body.