502 lines
18 KiB
TypeScript
502 lines
18 KiB
TypeScript
import * as path from 'path';
|
|
|
|
import {
|
|
AbiDefinition,
|
|
ConstructorAbi,
|
|
DataItem,
|
|
DevdocOutput,
|
|
EventAbi,
|
|
EventParameter,
|
|
FallbackAbi,
|
|
MethodAbi,
|
|
StandardContractOutput,
|
|
} from 'ethereum-types';
|
|
import ethUtil = require('ethereumjs-util');
|
|
import * as _ from 'lodash';
|
|
|
|
import { Compiler, CompilerOptions } from '@0xproject/sol-compiler';
|
|
import {
|
|
CustomType,
|
|
CustomTypeChild,
|
|
DocAgnosticFormat,
|
|
DocSection,
|
|
Event,
|
|
EventArg,
|
|
Parameter,
|
|
SolidityMethod,
|
|
Type,
|
|
TypeDocTypes,
|
|
} from '@0xproject/types';
|
|
|
|
// Unforunately, the only way to currently retrieve the declared structs with Solidity contracts
|
|
// is to tease it out of the params/return values included in it's ABI. These structures do
|
|
// not include the structs actual name, so we needed a mapping to assign the proper name to a
|
|
// struct. If the name is not in this mapping, the structs name will default to the param/return value
|
|
// name.
|
|
const customTypeHashToName: { [hash: string]: string } = {
|
|
'52d4a768701076c7bac06e386e430883975eb398732eccba797fd09dd064a60e': 'Order',
|
|
'46f7e8c4d144d11a72ce5338458ea37b933500d7a65e740cbca6d16e350eaa48': 'FillResult',
|
|
c22239cf0d29df1e6cf1be54f21692a8c0b3a48b9367540d4ffff4608b331ce9: 'OrderInfo',
|
|
c21e9ff31a30941c22e1cb43752114bb467c34dea58947f98966c9030fc8e4a9: 'TraderInfo',
|
|
'07c2bddc165e0b5005e6244dd4a9771fa61c78c4f42abd687d57567b0768136c': 'MatchedFillResult',
|
|
};
|
|
|
|
/**
|
|
* Invoke the Solidity compiler and transform its ABI and devdoc outputs into a
|
|
* JSON format easily consumed by documentation rendering tools.
|
|
* @param contractsToDocument list of contracts for which to generate doc objects
|
|
* @param contractsDir the directory in which to find the `contractsToCompile` as well as their dependencies.
|
|
* @return doc object for use with documentation generation tools.
|
|
*/
|
|
export async function generateSolDocAsync(
|
|
contractsDir: string,
|
|
contractsToDocument?: string[],
|
|
): Promise<DocAgnosticFormat> {
|
|
const docWithDependencies: DocAgnosticFormat = {};
|
|
const compilerOptions = _makeCompilerOptions(contractsDir, contractsToDocument);
|
|
const compiler = new Compiler(compilerOptions);
|
|
const compilerOutputs = await compiler.getCompilerOutputsAsync();
|
|
let structs: CustomType[] = [];
|
|
for (const compilerOutput of compilerOutputs) {
|
|
const contractFileNames = _.keys(compilerOutput.contracts);
|
|
for (const contractFileName of contractFileNames) {
|
|
const contractNameToOutput = compilerOutput.contracts[contractFileName];
|
|
|
|
const contractNames = _.keys(contractNameToOutput);
|
|
for (const contractName of contractNames) {
|
|
const compiledContract = contractNameToOutput[contractName];
|
|
if (_.isUndefined(compiledContract.abi)) {
|
|
throw new Error('compiled contract did not contain ABI output');
|
|
}
|
|
docWithDependencies[contractName] = _genDocSection(compiledContract, contractName);
|
|
structs = [...structs, ..._extractStructs(compiledContract)];
|
|
}
|
|
}
|
|
}
|
|
structs = _dedupStructs(structs);
|
|
structs = _overwriteStructNames(structs);
|
|
|
|
let doc: DocAgnosticFormat = {};
|
|
if (_.isUndefined(contractsToDocument) || contractsToDocument.length === 0) {
|
|
doc = docWithDependencies;
|
|
} else {
|
|
for (const contractToDocument of contractsToDocument) {
|
|
const contractBasename = path.basename(contractToDocument);
|
|
const contractName =
|
|
contractBasename.lastIndexOf('.sol') === -1
|
|
? contractBasename
|
|
: contractBasename.substring(0, contractBasename.lastIndexOf('.sol'));
|
|
doc[contractName] = docWithDependencies[contractName];
|
|
}
|
|
}
|
|
|
|
doc.structs = {
|
|
comment: '',
|
|
constructors: [],
|
|
methods: [],
|
|
properties: [],
|
|
types: structs,
|
|
functions: [],
|
|
events: [],
|
|
};
|
|
|
|
return doc;
|
|
}
|
|
|
|
function _makeCompilerOptions(contractsDir: string, contractsToCompile?: string[]): CompilerOptions {
|
|
const compilerOptions: CompilerOptions = {
|
|
contractsDir,
|
|
contracts: '*',
|
|
compilerSettings: {
|
|
outputSelection: {
|
|
['*']: {
|
|
['*']: ['abi', 'devdoc'],
|
|
},
|
|
},
|
|
},
|
|
};
|
|
|
|
const shouldOverrideCatchAllContractsConfig = !_.isUndefined(contractsToCompile) && contractsToCompile.length > 0;
|
|
if (shouldOverrideCatchAllContractsConfig) {
|
|
compilerOptions.contracts = contractsToCompile;
|
|
}
|
|
|
|
return compilerOptions;
|
|
}
|
|
|
|
function _extractStructs(compiledContract: StandardContractOutput): CustomType[] {
|
|
let customTypes: CustomType[] = [];
|
|
for (const abiDefinition of compiledContract.abi) {
|
|
switch (abiDefinition.type) {
|
|
case 'constructor': {
|
|
const types = _getStructsAsCustomTypes(abiDefinition);
|
|
customTypes = [...customTypes, ...types];
|
|
break;
|
|
}
|
|
case 'function': {
|
|
const types = _getStructsAsCustomTypes(abiDefinition);
|
|
customTypes = [...customTypes, ...types];
|
|
break;
|
|
}
|
|
case 'event':
|
|
case 'fallback':
|
|
// No types exist
|
|
break;
|
|
default:
|
|
throw new Error(
|
|
`unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`,
|
|
);
|
|
}
|
|
}
|
|
return customTypes;
|
|
}
|
|
|
|
function _genDocSection(compiledContract: StandardContractOutput, contractName: string): DocSection {
|
|
const docSection: DocSection = {
|
|
comment: _.isUndefined(compiledContract.devdoc) ? '' : compiledContract.devdoc.title,
|
|
constructors: [],
|
|
methods: [],
|
|
properties: [],
|
|
types: [],
|
|
functions: [],
|
|
events: [],
|
|
};
|
|
|
|
for (const abiDefinition of compiledContract.abi) {
|
|
switch (abiDefinition.type) {
|
|
case 'constructor':
|
|
docSection.constructors.push(_genConstructorDoc(contractName, abiDefinition, compiledContract.devdoc));
|
|
break;
|
|
case 'event':
|
|
(docSection.events as Event[]).push(_genEventDoc(abiDefinition));
|
|
// note that we're not sending devdoc to _genEventDoc().
|
|
// that's because the type of the events array doesn't have any fields for documentation!
|
|
break;
|
|
case 'function':
|
|
docSection.methods.push(_genMethodDoc(abiDefinition, compiledContract.devdoc));
|
|
break;
|
|
case 'fallback':
|
|
docSection.methods.push(_genFallbackDoc(abiDefinition, compiledContract.devdoc));
|
|
break;
|
|
default:
|
|
throw new Error(
|
|
`unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`,
|
|
);
|
|
}
|
|
}
|
|
|
|
return docSection;
|
|
}
|
|
|
|
function _genConstructorDoc(
|
|
contractName: string,
|
|
abiDefinition: ConstructorAbi,
|
|
devdocIfExists: DevdocOutput | undefined,
|
|
): SolidityMethod {
|
|
const { parameters, methodSignature } = _genMethodParamsDoc('', abiDefinition.inputs, devdocIfExists);
|
|
|
|
const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
|
|
|
|
const constructorDoc: SolidityMethod = {
|
|
isConstructor: true,
|
|
name: contractName,
|
|
callPath: '',
|
|
parameters,
|
|
returnType: { name: contractName, typeDocType: TypeDocTypes.Reference }, // sad we have to specify this
|
|
isConstant: false,
|
|
isPayable: abiDefinition.payable,
|
|
comment,
|
|
};
|
|
|
|
return constructorDoc;
|
|
}
|
|
|
|
function _devdocMethodDetailsIfExist(
|
|
methodSignature: string,
|
|
devdocIfExists: DevdocOutput | undefined,
|
|
): string | undefined {
|
|
let details;
|
|
if (!_.isUndefined(devdocIfExists)) {
|
|
const devdocMethodsIfExist = devdocIfExists.methods;
|
|
if (!_.isUndefined(devdocMethodsIfExist)) {
|
|
const devdocMethodIfExists = devdocMethodsIfExist[methodSignature];
|
|
if (!_.isUndefined(devdocMethodIfExists)) {
|
|
const devdocMethodDetailsIfExist = devdocMethodIfExists.details;
|
|
if (!_.isUndefined(devdocMethodDetailsIfExist)) {
|
|
details = devdocMethodDetailsIfExist;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
return details;
|
|
}
|
|
|
|
function _genFallbackDoc(abiDefinition: FallbackAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod {
|
|
const methodSignature = `()`;
|
|
const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
|
|
|
|
const returnComment =
|
|
_.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature])
|
|
? undefined
|
|
: devdocIfExists.methods[methodSignature].return;
|
|
|
|
const methodDoc: SolidityMethod = {
|
|
isConstructor: false,
|
|
name: 'fallback',
|
|
callPath: '',
|
|
parameters: [],
|
|
returnType: { name: 'void', typeDocType: TypeDocTypes.Intrinsic },
|
|
returnComment,
|
|
isConstant: true,
|
|
isPayable: abiDefinition.payable,
|
|
isFallback: true,
|
|
comment: _.isEmpty(comment)
|
|
? 'The default fallback function. It is executed on a call to the contract if none of the other functions match the given function identifier (or if no data was supplied at all).'
|
|
: comment,
|
|
};
|
|
return methodDoc;
|
|
}
|
|
|
|
function _genMethodDoc(abiDefinition: MethodAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod {
|
|
const name = abiDefinition.name;
|
|
const { parameters, methodSignature } = _genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists);
|
|
const devDocComment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
|
|
const returnType = _genMethodReturnTypeDoc(abiDefinition.outputs);
|
|
const returnComment =
|
|
_.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature])
|
|
? undefined
|
|
: devdocIfExists.methods[methodSignature].return;
|
|
|
|
const hasNoNamedParameters = _.isUndefined(_.find(parameters, p => !_.isEmpty(p.name)));
|
|
const isGeneratedGetter = hasNoNamedParameters;
|
|
const comment =
|
|
_.isEmpty(devDocComment) && isGeneratedGetter
|
|
? `This is an auto-generated accessor method of the '${name}' contract instance variable.`
|
|
: devDocComment;
|
|
const methodDoc: SolidityMethod = {
|
|
isConstructor: false,
|
|
name,
|
|
callPath: '',
|
|
parameters,
|
|
returnType,
|
|
returnComment,
|
|
isConstant: abiDefinition.constant,
|
|
isPayable: abiDefinition.payable,
|
|
comment,
|
|
};
|
|
return methodDoc;
|
|
}
|
|
|
|
function _genEventDoc(abiDefinition: EventAbi): Event {
|
|
const eventDoc: Event = {
|
|
name: abiDefinition.name,
|
|
eventArgs: _genEventArgsDoc(abiDefinition.inputs, undefined),
|
|
};
|
|
return eventDoc;
|
|
}
|
|
|
|
function _genEventArgsDoc(args: EventParameter[], devdocIfExists: DevdocOutput | undefined): EventArg[] {
|
|
const eventArgsDoc: EventArg[] = [];
|
|
|
|
for (const arg of args) {
|
|
const name = arg.name;
|
|
|
|
const type: Type = {
|
|
name: arg.type,
|
|
typeDocType: TypeDocTypes.Intrinsic,
|
|
};
|
|
|
|
const eventArgDoc: EventArg = {
|
|
isIndexed: arg.indexed,
|
|
name,
|
|
type,
|
|
};
|
|
|
|
eventArgsDoc.push(eventArgDoc);
|
|
}
|
|
return eventArgsDoc;
|
|
}
|
|
|
|
/**
|
|
* Extract documentation for each method parameter from @param params.
|
|
*/
|
|
function _genMethodParamsDoc(
|
|
name: string,
|
|
abiParams: DataItem[],
|
|
devdocIfExists: DevdocOutput | undefined,
|
|
): { parameters: Parameter[]; methodSignature: string } {
|
|
const parameters: Parameter[] = [];
|
|
for (const abiParam of abiParams) {
|
|
const type = _getTypeFromDataItem(abiParam);
|
|
|
|
const parameter: Parameter = {
|
|
name: abiParam.name,
|
|
comment: '<No comment>',
|
|
isOptional: false, // Unsupported in Solidity, until resolution of https://github.com/ethereum/solidity/issues/232
|
|
type,
|
|
};
|
|
parameters.push(parameter);
|
|
}
|
|
|
|
const methodSignature = `${name}(${abiParams
|
|
.map(abiParam => {
|
|
return abiParam.type;
|
|
})
|
|
.join(',')})`;
|
|
|
|
if (!_.isUndefined(devdocIfExists)) {
|
|
const devdocMethodIfExists = devdocIfExists.methods[methodSignature];
|
|
if (!_.isUndefined(devdocMethodIfExists)) {
|
|
const devdocParamsIfExist = devdocMethodIfExists.params;
|
|
if (!_.isUndefined(devdocParamsIfExist)) {
|
|
for (const parameter of parameters) {
|
|
parameter.comment = devdocParamsIfExist[parameter.name];
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
return { parameters, methodSignature };
|
|
}
|
|
|
|
function _genMethodReturnTypeDoc(outputs: DataItem[]): Type {
|
|
if (outputs.length > 1) {
|
|
const type: Type = {
|
|
name: '',
|
|
typeDocType: TypeDocTypes.Tuple,
|
|
tupleElements: [],
|
|
};
|
|
for (const output of outputs) {
|
|
const tupleType = _getTypeFromDataItem(output);
|
|
(type.tupleElements as Type[]).push(tupleType);
|
|
}
|
|
return type;
|
|
} else if (outputs.length === 1) {
|
|
const output = outputs[0];
|
|
const type = _getTypeFromDataItem(output);
|
|
return type;
|
|
} else {
|
|
const type: Type = {
|
|
name: 'void',
|
|
typeDocType: TypeDocTypes.Intrinsic,
|
|
};
|
|
return type;
|
|
}
|
|
}
|
|
|
|
function _capitalize(text: string): string {
|
|
return `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
|
|
}
|
|
|
|
function _dedupStructs(customTypes: CustomType[]): CustomType[] {
|
|
const uniqueCustomTypes: CustomType[] = [];
|
|
const seenTypes: { [hash: string]: boolean } = {};
|
|
_.each(customTypes, customType => {
|
|
const hash = _generateCustomTypeHash(customType);
|
|
if (!seenTypes[hash]) {
|
|
uniqueCustomTypes.push(customType);
|
|
seenTypes[hash] = true;
|
|
}
|
|
});
|
|
return uniqueCustomTypes;
|
|
}
|
|
|
|
function _overwriteStructNames(customTypes: CustomType[]): CustomType[] {
|
|
const localCustomTypes = _.cloneDeep(customTypes);
|
|
_.each(localCustomTypes, customType => {
|
|
const hash = _generateCustomTypeHash(customType);
|
|
if (!_.isUndefined(customTypeHashToName[hash])) {
|
|
customType.name = customTypeHashToName[hash];
|
|
}
|
|
});
|
|
return localCustomTypes;
|
|
}
|
|
|
|
function _generateCustomTypeHash(customType: CustomType): string {
|
|
const customTypeWithoutName = _.cloneDeep(customType);
|
|
delete customTypeWithoutName.name;
|
|
const customTypeWithoutNameStr = JSON.stringify(customTypeWithoutName);
|
|
const hash = ethUtil.sha256(customTypeWithoutNameStr).toString('hex');
|
|
return hash;
|
|
}
|
|
|
|
function _getStructsAsCustomTypes(abiDefinition: AbiDefinition): CustomType[] {
|
|
const customTypes: CustomType[] = [];
|
|
if (!_.isUndefined((abiDefinition as any).inputs)) {
|
|
const methodOrConstructorAbi = abiDefinition as MethodAbi | ConstructorAbi;
|
|
_.each(methodOrConstructorAbi.inputs, input => {
|
|
if (!_.isUndefined(input.components)) {
|
|
const customType = _getCustomTypeFromDataItem(input);
|
|
customTypes.push(customType);
|
|
}
|
|
});
|
|
}
|
|
if (!_.isUndefined((abiDefinition as any).outputs)) {
|
|
const methodAbi = abiDefinition as MethodAbi;
|
|
_.each(methodAbi.outputs, output => {
|
|
if (!_.isUndefined(output.components)) {
|
|
const customType = _getCustomTypeFromDataItem(output);
|
|
customTypes.push(customType);
|
|
}
|
|
});
|
|
}
|
|
return customTypes;
|
|
}
|
|
|
|
function _getCustomTypeFromDataItem(inputOrOutput: DataItem): CustomType {
|
|
const customType: CustomType = {
|
|
name: _.capitalize(inputOrOutput.name),
|
|
kindString: 'Interface',
|
|
children: [],
|
|
};
|
|
_.each(inputOrOutput.components, (component: DataItem) => {
|
|
const childType = _getTypeFromDataItem(component);
|
|
const customTypeChild = {
|
|
name: component.name,
|
|
type: childType,
|
|
};
|
|
// (fabio): Not sure why this type casting is necessary. Seems TS doesn't
|
|
// deduce that `customType.children` cannot be undefined anymore after being
|
|
// set to `[]` above.
|
|
(customType.children as CustomTypeChild[]).push(customTypeChild);
|
|
});
|
|
return customType;
|
|
}
|
|
|
|
function _getNameFromDataItemIfExists(dataItem: DataItem): string | undefined {
|
|
if (_.isUndefined(dataItem.components)) {
|
|
return undefined;
|
|
}
|
|
const customType = _getCustomTypeFromDataItem(dataItem);
|
|
const hash = _generateCustomTypeHash(customType);
|
|
if (_.isUndefined(customTypeHashToName[hash])) {
|
|
return undefined;
|
|
}
|
|
return customTypeHashToName[hash];
|
|
}
|
|
|
|
function _getTypeFromDataItem(dataItem: DataItem): Type {
|
|
const typeDocType = !_.isUndefined(dataItem.components) ? TypeDocTypes.Reference : TypeDocTypes.Intrinsic;
|
|
let typeName: string;
|
|
if (typeDocType === TypeDocTypes.Reference) {
|
|
const nameIfExists = _getNameFromDataItemIfExists(dataItem);
|
|
typeName = _.isUndefined(nameIfExists) ? _capitalize(dataItem.name) : nameIfExists;
|
|
} else {
|
|
typeName = dataItem.type;
|
|
}
|
|
|
|
const isArrayType = _.endsWith(dataItem.type, '[]');
|
|
let type: Type;
|
|
if (isArrayType) {
|
|
typeName = typeDocType === TypeDocTypes.Intrinsic ? typeName.slice(0, -2) : typeName;
|
|
type = {
|
|
elementType: { name: typeName, typeDocType },
|
|
typeDocType: TypeDocTypes.Array,
|
|
name: '',
|
|
};
|
|
} else {
|
|
type = { name: typeName, typeDocType };
|
|
}
|
|
return type;
|
|
}
|