diff options
Diffstat (limited to 'packages')
31 files changed, 958 insertions, 359 deletions
diff --git a/packages/ethereum-types/src/index.ts b/packages/ethereum-types/src/index.ts index 3b6fdc77b..b4c9b73ca 100644 --- a/packages/ethereum-types/src/index.ts +++ b/packages/ethereum-types/src/index.ts @@ -324,9 +324,56 @@ export interface ContractNetworkData { constructorArgs: string; } +export type ParamDescription = string; + export interface StandardContractOutput { abi: ContractAbi; evm: EvmOutput; + devdoc?: DevdocOutput; +} + +export interface StandardOutput { + errors: SolcError[]; + sources: { + [fileName: string]: { + id: number; + ast?: object; + legacyAST?: object; + }; + }; + contracts: { + [fileName: string]: { + [contractName: string]: StandardContractOutput; + }; + }; +} + +export type ErrorType = + | 'JSONError' + | 'IOError' + | 'ParserError' + | 'DocstringParsingError' + | 'SyntaxError' + | 'DeclarationError' + | 'TypeError' + | 'UnimplementedFeatureError' + | 'InternalCompilerError' + | 'Exception' + | 'CompilerError' + | 'FatalError' + | 'Warning'; +export type ErrorSeverity = 'error' | 'warning'; +export interface SolcError { + sourceLocation?: { + file: string; + start: number; + end: number; + }; + type: ErrorType; + component: 'general' | 'ewasm'; + severity: ErrorSeverity; + message: string; + formattedMessage?: string; } export interface EvmOutput { @@ -339,6 +386,20 @@ export interface EvmBytecodeOutput { sourceMap: string; } +export interface DevdocOutput { + title: string; + author: string; + methods: { + [signature: string]: { + details: string; + params: { + [name: string]: ParamDescription; + }; + return?: string; + }; + }; +} + export interface ContractVersionData { compiler: CompilerOpts; sources: { diff --git a/packages/react-docs/package.json b/packages/react-docs/package.json index 345522074..53c5fbb3f 100644 --- a/packages/react-docs/package.json +++ b/packages/react-docs/package.json @@ -34,6 +34,7 @@ }, "dependencies": { "@0xproject/react-shared": "^1.0.9", + "@0xproject/types": "^1.0.1-rc.6", "@0xproject/utils": "^1.0.8", "@types/lodash": "4.14.104", "@types/material-ui": "^0.20.0", diff --git a/packages/react-docs/src/components/custom_enum.tsx b/packages/react-docs/src/components/custom_enum.tsx index c4252d9e2..fa7c43146 100644 --- a/packages/react-docs/src/components/custom_enum.tsx +++ b/packages/react-docs/src/components/custom_enum.tsx @@ -2,7 +2,7 @@ import { logUtils } from '@0xproject/utils'; import * as _ from 'lodash'; import * as React from 'react'; -import { CustomType } from '../types'; +import { CustomType } from '@0xproject/types'; const STRING_ENUM_CODE_PREFIX = ' strEnum('; diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 9d9b5141a..16a99713c 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -9,24 +9,23 @@ import { Styles, utils as sharedUtils, } from '@0xproject/react-shared'; -import * as _ from 'lodash'; -import CircularProgress from 'material-ui/CircularProgress'; -import * as React from 'react'; -import * as semver from 'semver'; - -import { DocsInfo } from '../docs_info'; import { - AddressByContractName, DocAgnosticFormat, Event, ExternalExportToLink, Property, SolidityMethod, - SupportedDocJson, TypeDefinitionByName, TypescriptFunction, TypescriptMethod, -} from '../types'; +} from '@0xproject/types'; +import * as _ from 'lodash'; +import CircularProgress from 'material-ui/CircularProgress'; +import * as React from 'react'; +import * as semver from 'semver'; + +import { DocsInfo } from '../docs_info'; +import { AddressByContractName, SupportedDocJson } from '../types'; import { constants } from '../utils/constants'; import { Badge } from './badge'; diff --git a/packages/react-docs/src/components/event_definition.tsx b/packages/react-docs/src/components/event_definition.tsx index 6cb80c6b0..37236275b 100644 --- a/packages/react-docs/src/components/event_definition.tsx +++ b/packages/react-docs/src/components/event_definition.tsx @@ -1,9 +1,9 @@ import { AnchorTitle, colors, HeaderSizes } from '@0xproject/react-shared'; +import { Event, EventArg } from '@0xproject/types'; import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { Event, EventArg } from '../types'; import { Type } from './type'; diff --git a/packages/react-docs/src/components/interface.tsx b/packages/react-docs/src/components/interface.tsx index 93b10e96d..9f0800d71 100644 --- a/packages/react-docs/src/components/interface.tsx +++ b/packages/react-docs/src/components/interface.tsx @@ -1,8 +1,9 @@ import * as _ from 'lodash'; import * as React from 'react'; +import { CustomType, TypeDefinitionByName } from '@0xproject/types'; + import { DocsInfo } from '../docs_info'; -import { CustomType, TypeDefinitionByName } from '../types'; import { Signature } from './signature'; import { Type } from './type'; diff --git a/packages/react-docs/src/components/property_block.tsx b/packages/react-docs/src/components/property_block.tsx index f181e21d2..8434e8682 100644 --- a/packages/react-docs/src/components/property_block.tsx +++ b/packages/react-docs/src/components/property_block.tsx @@ -1,8 +1,8 @@ import { AnchorTitle, HeaderSizes } from '@0xproject/react-shared'; +import { Property, TypeDefinitionByName } from '@0xproject/types'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { Property, TypeDefinitionByName } from '../types'; import { constants } from '../utils/constants'; import { Comment } from './comment'; diff --git a/packages/react-docs/src/components/signature.tsx b/packages/react-docs/src/components/signature.tsx index bf9c8be24..9eb8a7d86 100644 --- a/packages/react-docs/src/components/signature.tsx +++ b/packages/react-docs/src/components/signature.tsx @@ -1,8 +1,9 @@ import * as _ from 'lodash'; import * as React from 'react'; +import { Parameter, Type as TypeDef, TypeDefinitionByName, TypeParameter } from '@0xproject/types'; + import { DocsInfo } from '../docs_info'; -import { Parameter, Type as TypeDef, TypeDefinitionByName, TypeParameter } from '../types'; import { Type } from './type'; diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index 05145dc23..1ea0ea28c 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -1,9 +1,15 @@ import { AnchorTitle, colors, HeaderSizes, Styles } from '@0xproject/react-shared'; +import { + Parameter, + SolidityMethod, + TypeDefinitionByName, + TypescriptFunction, + TypescriptMethod, +} from '@0xproject/types'; import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { Parameter, SolidityMethod, TypeDefinitionByName, TypescriptFunction, TypescriptMethod } from '../types'; import { constants } from '../utils/constants'; import { Comment } from './comment'; diff --git a/packages/react-docs/src/components/source_link.tsx b/packages/react-docs/src/components/source_link.tsx index c60435ea6..3096ad8d5 100644 --- a/packages/react-docs/src/components/source_link.tsx +++ b/packages/react-docs/src/components/source_link.tsx @@ -1,8 +1,7 @@ import { colors } from '@0xproject/react-shared'; +import { Source } from '@0xproject/types'; import * as React from 'react'; -import { Source } from '../types'; - export interface SourceLinkProps { source: Source; sourceUrl: string; diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 5f7601ce1..156a3496d 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -1,4 +1,5 @@ import { colors, constants as sharedConstants, utils as sharedUtils } from '@0xproject/react-shared'; +import { Type as TypeDef, TypeDefinitionByName, TypeDocTypes } from '@0xproject/types'; import { errorUtils } from '@0xproject/utils'; import * as _ from 'lodash'; import * as React from 'react'; @@ -6,7 +7,6 @@ import { Link as ScrollLink } from 'react-scroll'; import * as ReactTooltip from 'react-tooltip'; import { DocsInfo } from '../docs_info'; -import { Type as TypeDef, TypeDefinitionByName, TypeDocTypes } from '../types'; import { constants } from '../utils/constants'; import { Signature } from './signature'; diff --git a/packages/react-docs/src/components/type_definition.tsx b/packages/react-docs/src/components/type_definition.tsx index 8d1f88490..09cb3ff74 100644 --- a/packages/react-docs/src/components/type_definition.tsx +++ b/packages/react-docs/src/components/type_definition.tsx @@ -1,10 +1,11 @@ import { AnchorTitle, colors, HeaderSizes } from '@0xproject/react-shared'; +import { CustomType, CustomTypeChild, TypeDefinitionByName, TypeDocTypes } from '@0xproject/types'; import { errorUtils } from '@0xproject/utils'; import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { CustomType, CustomTypeChild, KindString, TypeDefinitionByName, TypeDocTypes } from '../types'; +import { KindString } from '../types'; import { constants } from '../utils/constants'; import { Comment } from './comment'; diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts index dec44458d..fa5aa0da3 100644 --- a/packages/react-docs/src/docs_info.ts +++ b/packages/react-docs/src/docs_info.ts @@ -1,17 +1,15 @@ import { MenuSubsectionsBySection } from '@0xproject/react-shared'; +import { DocAgnosticFormat, GeneratedDocJson, TypeDefinitionByName } from '@0xproject/types'; import * as _ from 'lodash'; import { ContractsByVersionByNetworkId, - DocAgnosticFormat, DocsInfoConfig, DocsMenu, DoxityDocObj, - GeneratedDocJson, SectionNameToMarkdownByVersion, SectionsMap, SupportedDocJson, - TypeDefinitionByName, } from './types'; import { doxityUtils } from './utils/doxity_utils'; import { TypeDocUtils } from './utils/typedoc_utils'; diff --git a/packages/react-docs/src/index.ts b/packages/react-docs/src/index.ts index e4424f679..8a2c215b8 100644 --- a/packages/react-docs/src/index.ts +++ b/packages/react-docs/src/index.ts @@ -1,3 +1,5 @@ +export { DocAgnosticFormat, GeneratedDocJson } from '@0xproject/types'; + // Exported to give users of this library added flexibility if they want to build // a docs page from scratch using the individual components. export { Badge } from './components/badge'; @@ -15,14 +17,6 @@ export { Type } from './components/type'; export { DocsInfo } from './docs_info'; -export { - DocsInfoConfig, - DocAgnosticFormat, - DoxityDocObj, - DocsMenu, - SupportedDocJson, - TypeDocNode, - GeneratedDocJson, -} from './types'; +export { DocsInfoConfig, DoxityDocObj, DocsMenu, SupportedDocJson } from './types'; export { constants } from './utils/constants'; diff --git a/packages/react-docs/src/types.ts b/packages/react-docs/src/types.ts index f9cb5e26a..454190342 100644 --- a/packages/react-docs/src/types.ts +++ b/packages/react-docs/src/types.ts @@ -22,72 +22,6 @@ export interface SectionsMap { [sectionName: string]: string; } -export interface TypeDocType { - type: TypeDocTypes; - value: string; - name: string; - types: TypeDocType[]; - typeArguments?: TypeDocType[]; - declaration: TypeDocNode; - elementType?: TypeDocType; - indexSignature?: TypeDocNode; - elements?: TupleElement[]; -} - -export interface TupleElement { - type: string; - name: string; -} - -export interface TypeDocFlags { - isStatic?: boolean; - isOptional?: boolean; - isPublic?: boolean; - isExported?: boolean; -} - -export interface TypeDocGroup { - title: string; - children: number[]; -} - -export interface TypeDocNode { - id?: number; - name?: string; - kind?: string; - defaultValue?: string; - kindString?: string; - type?: TypeDocType; - fileName?: string; - line?: number; - comment?: TypeDocNode; - text?: string; - shortText?: string; - returns?: string; - declaration: TypeDocNode; - flags?: TypeDocFlags; - indexSignature?: TypeDocNode; - signatures?: TypeDocNode[]; - parameters?: TypeDocNode[]; - typeParameter?: TypeDocNode[]; - sources?: TypeDocNode[]; - children?: TypeDocNode[]; - groups?: TypeDocGroup[]; -} - -export enum TypeDocTypes { - Intrinsic = 'intrinsic', - Reference = 'reference', - Array = 'array', - StringLiteral = 'stringLiteral', - Reflection = 'reflection', - Union = 'union', - TypeParameter = 'typeParameter', - Intersection = 'intersection', - Tuple = 'tuple', - Unknown = 'unknown', -} - // Exception: We don't make the values uppercase because these KindString's need to // match up those returned by TypeDoc export enum KindString { @@ -103,139 +37,6 @@ export enum KindString { Class = 'Class', } -export interface DocAgnosticFormat { - [sectionName: string]: DocSection; -} - -export interface DocSection { - comment: string; - constructors: Array<TypescriptMethod | SolidityMethod>; - methods: Array<TypescriptMethod | SolidityMethod>; - properties: Property[]; - types: CustomType[]; - functions: TypescriptFunction[]; - events?: Event[]; - externalExportToLink?: ExternalExportToLink; -} - -export interface TypescriptMethod extends BaseMethod { - source?: Source; - isStatic?: boolean; - typeParameter?: TypeParameter; -} - -export interface TypescriptFunction extends BaseFunction { - source?: Source; - typeParameter?: TypeParameter; - callPath: string; -} - -export interface SolidityMethod extends BaseMethod { - isConstant?: boolean; - isPayable?: boolean; -} - -export interface Source { - fileName: string; - line: number; -} - -export interface Parameter { - name: string; - comment: string; - isOptional: boolean; - type: Type; - defaultValue?: string; -} - -export interface TypeParameter { - name: string; - type: Type; -} - -export interface Type { - name: string; - typeDocType: TypeDocTypes; - value?: string; - isExportedClassReference?: boolean; - typeArguments?: Type[]; - elementType?: ElementType; - types?: Type[]; - method?: TypescriptMethod; - indexSignature?: IndexSignature; - externalLink?: string; - tupleElements?: Type[]; -} - -export interface ElementType { - name: string; - typeDocType: TypeDocTypes; -} - -export interface IndexSignature { - keyName: string; - keyType: Type; - valueName: string; -} - -export interface CustomType { - name: string; - kindString: string; - type?: Type; - method?: TypescriptMethod; - indexSignature?: IndexSignature; - defaultValue?: string; - comment?: string; - children?: CustomTypeChild[]; -} - -export interface CustomTypeChild { - name: string; - type?: Type; - defaultValue?: string; -} - -export interface Event { - name: string; - eventArgs: EventArg[]; -} - -export interface EventArg { - isIndexed: boolean; - name: string; - type: Type; -} - -export interface Property { - name: string; - type: Type; - source?: Source; - comment?: string; - callPath?: string; -} - -export interface BaseMethod { - isConstructor: boolean; - name: string; - returnComment?: string | undefined; - callPath: string; - parameters: Parameter[]; - returnType: Type; - comment?: string; -} - -export interface BaseFunction { - name: string; - returnComment?: string | undefined; - parameters: Parameter[]; - returnType: Type; - comment?: string; -} - -export interface TypeDefinitionByName { - [typeName: string]: CustomType; -} - export enum SupportedDocJson { Doxity = 'DOXITY', TypeDoc = 'TYPEDOC', @@ -297,28 +98,3 @@ export enum AbiTypes { Function = 'function', Event = 'event', } - -export interface ExportNameToTypedocNames { - [exportName: string]: string[]; -} - -export interface ExternalTypeToLink { - [externalTypeName: string]: string; -} - -export interface ExternalExportToLink { - [externalExport: string]: string; -} - -export interface Metadata { - exportPathToTypedocNames: ExportNameToTypedocNames; - exportPathOrder: string[]; - externalTypeToLink: ExternalTypeToLink; - externalExportToLink: ExternalExportToLink; -} - -export interface GeneratedDocJson { - version: string; - metadata: Metadata; - typedocJson: TypeDocNode; -} diff --git a/packages/react-docs/src/utils/doxity_utils.ts b/packages/react-docs/src/utils/doxity_utils.ts index 6815daa0c..85794d4ba 100644 --- a/packages/react-docs/src/utils/doxity_utils.ts +++ b/packages/react-docs/src/utils/doxity_utils.ts @@ -1,20 +1,17 @@ import * as _ from 'lodash'; import { - AbiTypes, DocAgnosticFormat, DocSection, - DoxityAbiDoc, - DoxityContractObj, - DoxityDocObj, - DoxityInput, EventArg, Parameter, Property, SolidityMethod, Type, TypeDocTypes, -} from '../types'; +} from '@0xproject/types'; + +import { AbiTypes, DoxityAbiDoc, DoxityContractObj, DoxityDocObj, DoxityInput } from '../types'; export const doxityUtils = { convertToDocAgnosticFormat(doxityDocObj: DoxityDocObj): DocAgnosticFormat { diff --git a/packages/react-docs/src/utils/typedoc_utils.ts b/packages/react-docs/src/utils/typedoc_utils.ts index f44945369..d235b4406 100644 --- a/packages/react-docs/src/utils/typedoc_utils.ts +++ b/packages/react-docs/src/utils/typedoc_utils.ts @@ -1,7 +1,3 @@ -import { errorUtils } from '@0xproject/utils'; -import * as _ from 'lodash'; - -import { DocsInfo } from '../docs_info'; import { CustomType, CustomTypeChild, @@ -11,7 +7,6 @@ import { ExternalTypeToLink, GeneratedDocJson, IndexSignature, - KindString, Parameter, Property, Type, @@ -21,7 +16,12 @@ import { TypeParameter, TypescriptFunction, TypescriptMethod, -} from '../types'; +} from '@0xproject/types'; +import { errorUtils } from '@0xproject/utils'; +import * as _ from 'lodash'; + +import { DocsInfo } from '../docs_info'; +import { KindString } from '../types'; import { constants } from './constants'; @@ -468,6 +468,7 @@ export class TypeDocUtils { methodIfExists = this._convertMethod(entity.declaration, isConstructor, sectionName); } else if (entity.type === TypeDocTypes.Tuple) { tupleElementsIfExists = _.map(entity.elements, el => { + // tslint:disable-next-line:no-unnecessary-type-assertion return { name: el.name, typeDocType: el.type as TypeDocTypes }; }); } diff --git a/packages/sol-compiler/src/compiler.ts b/packages/sol-compiler/src/compiler.ts index 7c76f3e52..3b0bd90f9 100644 --- a/packages/sol-compiler/src/compiler.ts +++ b/packages/sol-compiler/src/compiler.ts @@ -10,7 +10,7 @@ import { } from '@0xproject/sol-resolver'; import { fetchAsync, logUtils } from '@0xproject/utils'; import chalk from 'chalk'; -import { CompilerOptions, ContractArtifact, ContractVersionData } from 'ethereum-types'; +import { CompilerOptions, ContractArtifact, ContractVersionData, StandardOutput } from 'ethereum-types'; import * as ethUtil from 'ethereumjs-util'; import * as fs from 'fs'; import * as _ from 'lodash'; @@ -110,6 +110,21 @@ export class Compiler { const solcInstance = solc.setupMethods(requireFromString(solcjs, compilerBinFilename)); return { solcInstance, fullSolcVersion }; } + private static _addHexPrefixToContractBytecode(compiledContract: solc.StandardContractOutput): void { + if (!_.isUndefined(compiledContract.evm)) { + if (!_.isUndefined(compiledContract.evm.bytecode) && !_.isUndefined(compiledContract.evm.bytecode.object)) { + compiledContract.evm.bytecode.object = ethUtil.addHexPrefix(compiledContract.evm.bytecode.object); + } + if ( + !_.isUndefined(compiledContract.evm.deployedBytecode) && + !_.isUndefined(compiledContract.evm.deployedBytecode.object) + ) { + compiledContract.evm.deployedBytecode.object = ethUtil.addHexPrefix( + compiledContract.evm.deployedBytecode.object, + ); + } + } + } /** * Instantiates a new instance of the Compiler class. * @param opts Optional compiler options @@ -144,7 +159,22 @@ export class Compiler { public async compileAsync(): Promise<void> { await createDirIfDoesNotExistAsync(this._artifactsDir); await createDirIfDoesNotExistAsync(SOLC_BIN_DIR); - let contractNamesToCompile: string[] = []; + await this._compileContractsAsync(this._getContractNamesToCompile(), true); + } + /** + * Compiles Solidity files specified during instantiation, and returns the + * compiler output given by solc. Return value is an array of outputs: + * Solidity modules are batched together by version required, and each + * element of the returned array corresponds to a compiler version, and + * each element contains the output for all of the modules compiled with + * that version. + */ + public async getCompilerOutputsAsync(): Promise<StandardOutput[]> { + const promisedOutputs = this._compileContractsAsync(this._getContractNamesToCompile(), false); + return promisedOutputs; + } + private _getContractNamesToCompile(): string[] { + let contractNamesToCompile; if (this._specifiedContracts === ALL_CONTRACTS_IDENTIFIER) { const allContracts = this._nameResolver.getAll(); contractNamesToCompile = _.map(allContracts, contractSource => @@ -153,13 +183,14 @@ export class Compiler { } else { contractNamesToCompile = this._specifiedContracts; } - await this._compileContractsAsync(contractNamesToCompile); + return contractNamesToCompile; } /** - * Compiles contract and saves artifact to artifactsDir. + * Compiles contracts, and, if `shouldPersist` is true, saves artifacts to artifactsDir. * @param fileName Name of contract with '.sol' extension. + * @return an array of compiler outputs, where each element corresponds to a different version of solc-js. */ - private async _compileContractsAsync(contractNames: string[]): Promise<void> { + private async _compileContractsAsync(contractNames: string[], shouldPersist: boolean): Promise<StandardOutput[]> { // batch input contracts together based on the version of the compiler that they require. const versionToInputs: VersionToInputs = {}; @@ -200,6 +231,8 @@ export class Compiler { versionToInputs[solcVersion].contractsToCompile.push(contractSource.path); } + const compilerOutputs: StandardOutput[] = []; + const solcVersions = _.keys(versionToInputs); for (const solcVersion of solcVersions) { const input = versionToInputs[solcVersion]; @@ -212,18 +245,34 @@ export class Compiler { const { solcInstance, fullSolcVersion } = await Compiler._getSolcAsync(solcVersion); const compilerOutput = this._compile(solcInstance, input.standardInput); + compilerOutputs.push(compilerOutput); for (const contractPath of input.contractsToCompile) { - await this._verifyAndPersistCompiledContractAsync( - contractPath, - contractPathToData[contractPath].currentArtifactIfExists, - contractPathToData[contractPath].sourceTreeHashHex, - contractPathToData[contractPath].contractName, - fullSolcVersion, - compilerOutput, - ); + const contractName = contractPathToData[contractPath].contractName; + + const compiledContract = compilerOutput.contracts[contractPath][contractName]; + if (_.isUndefined(compiledContract)) { + throw new Error( + `Contract ${contractName} not found in ${contractPath}. Please make sure your contract has the same name as it's file name`, + ); + } + + Compiler._addHexPrefixToContractBytecode(compiledContract); + + if (shouldPersist) { + await this._persistCompiledContractAsync( + contractPath, + contractPathToData[contractPath].currentArtifactIfExists, + contractPathToData[contractPath].sourceTreeHashHex, + contractName, + fullSolcVersion, + compilerOutput, + ); + } } } + + return compilerOutputs; } private _shouldCompile(contractData: ContractData): boolean { if (_.isUndefined(contractData.currentArtifactIfExists)) { @@ -236,7 +285,7 @@ export class Compiler { return !isUserOnLatestVersion || didCompilerSettingsChange || didSourceChange; } } - private async _verifyAndPersistCompiledContractAsync( + private async _persistCompiledContractAsync( contractPath: string, currentArtifactIfExists: ContractArtifact | void, sourceTreeHashHex: string, @@ -244,32 +293,13 @@ export class Compiler { fullSolcVersion: string, compilerOutput: solc.StandardOutput, ): Promise<void> { - const compiledData = compilerOutput.contracts[contractPath][contractName]; - if (_.isUndefined(compiledData)) { - throw new Error( - `Contract ${contractName} not found in ${contractPath}. Please make sure your contract has the same name as it's file name`, - ); - } - if (!_.isUndefined(compiledData.evm)) { - if (!_.isUndefined(compiledData.evm.bytecode) && !_.isUndefined(compiledData.evm.bytecode.object)) { - compiledData.evm.bytecode.object = ethUtil.addHexPrefix(compiledData.evm.bytecode.object); - } - if ( - !_.isUndefined(compiledData.evm.deployedBytecode) && - !_.isUndefined(compiledData.evm.deployedBytecode.object) - ) { - compiledData.evm.deployedBytecode.object = ethUtil.addHexPrefix( - compiledData.evm.deployedBytecode.object, - ); - } - } - + const compiledContract = compilerOutput.contracts[contractPath][contractName]; const sourceCodes = _.mapValues( compilerOutput.sources, (_1, sourceFilePath) => this._resolver.resolve(sourceFilePath).source, ); const contractVersion: ContractVersionData = { - compilerOutput: compiledData, + compilerOutput: compiledContract, sources: compilerOutput.sources, sourceCodes, sourceTreeHashHex, diff --git a/packages/sol-compiler/src/index.ts b/packages/sol-compiler/src/index.ts index f8c2b577a..829e515ff 100644 --- a/packages/sol-compiler/src/index.ts +++ b/packages/sol-compiler/src/index.ts @@ -1,8 +1,28 @@ export { Compiler } from './compiler'; export { + AbiDefinition, CompilerOptions, CompilerSettings, + DataItem, + DevdocOutput, + ErrorSeverity, + ErrorType, + EventAbi, + EventParameter, + EvmBytecodeOutput, + EvmOutput, + FallbackAbi, + FunctionAbi, + MethodAbi, + ConstructorAbi, + ConstructorStateMutability, + ContractAbi, OutputField, CompilerSettingsMetadata, OptimizerSettings, + ParamDescription, + SolcError, + StandardContractOutput, + StandardOutput, + StateMutability, } from 'ethereum-types'; diff --git a/packages/sol-doc/coverage/.gitkeep b/packages/sol-doc/coverage/.gitkeep new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/packages/sol-doc/coverage/.gitkeep diff --git a/packages/sol-doc/package.json b/packages/sol-doc/package.json new file mode 100644 index 000000000..e3bc8753c --- /dev/null +++ b/packages/sol-doc/package.json @@ -0,0 +1,41 @@ +{ + "name": "@0xproject/sol-doc", + "version": "1.0.0", + "description": "Solidity documentation generator", + "main": "lib/src/index.js", + "types": "lib/src/index.d.js", + "scripts": { + "build": "tsc", + "test": "mocha --require source-map-support/register --require make-promises-safe lib/test/**/*_test.js --timeout 5000 --exit", + "test:circleci": "yarn test:coverage", + "test:coverage": "nyc npm run test --all && yarn coverage:report:lcov", + "coverage:report:lcov": "nyc report --reporter=text-lcov > coverage/lcov.info", + "lint": "tslint --project . --format stylish", + "clean": "shx rm -rf lib" + }, + "repository": "https://github.com/0xProject/0x-monorepo.git", + "author": "F. Eugene Aumson", + "license": "Apache-2.0", + "dependencies": { + "@0xproject/sol-compiler": "^1.0.5", + "@0xproject/types": "^1.0.1-rc.6", + "@0xproject/utils": "^1.0.5", + "ethereum-types": "^1.0.4", + "lodash": "^4.17.10" + }, + "devDependencies": { + "@0xproject/tslint-config": "^1.0.6", + "chai": "^4.1.2", + "chai-as-promised": "^7.1.0", + "chai-bignumber": "^2.0.2", + "dirty-chai": "^2.0.1", + "make-promises-safe": "^1.1.0", + "mocha": "^5.2.0", + "shx": "^0.2.2", + "source-map-support": "^0.5.0", + "tslint": "5.11.0" + }, + "publishConfig": { + "access": "public" + } +} diff --git a/packages/sol-doc/src/index.ts b/packages/sol-doc/src/index.ts new file mode 100644 index 000000000..03f3c9de6 --- /dev/null +++ b/packages/sol-doc/src/index.ts @@ -0,0 +1 @@ +export { generateSolDocAsync } from './solidity_doc_generator'; diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts new file mode 100644 index 000000000..a1ef32e79 --- /dev/null +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -0,0 +1,284 @@ +import * as _ from 'lodash'; + +import { + ConstructorAbi, + DataItem, + DevdocOutput, + EventAbi, + FallbackAbi, + MethodAbi, + StandardContractOutput, +} from 'ethereum-types'; + +import { Compiler, CompilerOptions } from '@0xproject/sol-compiler'; +import { + DocAgnosticFormat, + DocSection, + Event, + EventArg, + Parameter, + SolidityMethod, + Type, + TypeDocTypes, +} from '@0xproject/types'; + +/** + * Invoke the Solidity compiler and transform its ABI and devdoc outputs into + * the types that are used as input to documentation generation tools. + * @param contractsToCompile 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( + contractsToCompile: string[], + contractsDir: string, +): Promise<DocAgnosticFormat> { + const doc: DocAgnosticFormat = {}; + + const compilerOptions = _makeCompilerOptions(contractsToCompile, contractsDir); + const compiler = new Compiler(compilerOptions); + const compilerOutputs = await compiler.getCompilerOutputsAsync(); + 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'); + } + doc[contractName] = _genDocSection(compiledContract); + } + } + } + + return doc; +} + +function _makeCompilerOptions(contractsToCompile: string[], contractsDir: string): CompilerOptions { + const compilerOptions: CompilerOptions = { + contractsDir, + contracts: '*', + compilerSettings: { + outputSelection: { + ['*']: { + ['*']: ['abi', 'devdoc'], + }, + }, + }, + }; + + const shouldOverrideCatchAllContractsConfig = !_.isUndefined(contractsToCompile); + if (shouldOverrideCatchAllContractsConfig) { + compilerOptions.contracts = contractsToCompile; + } + + return compilerOptions; +} + +function _genDocSection(compiledContract: StandardContractOutput): 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(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; + default: + throw new Error(`unknown and unsupported AbiDefinition type '${abiDefinition.type}'`); + } + } + + return docSection; +} + +function _genConstructorDoc(abiDefinition: ConstructorAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod { + const { parameters, methodSignature } = _genMethodParamsDoc( + '', // TODO: update depending on how constructors are keyed in devdoc + abiDefinition.inputs, + devdocIfExists, + ); + + const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists); + // TODO: figure out why devdoc'd constructors don't get output by solc + + const constructorDoc: SolidityMethod = { + isConstructor: true, + name: '', // sad we have to specify this + callPath: '', // TODO: wtf is this? + parameters, + returnType: { name: '', typeDocType: TypeDocTypes.Intrinsic }, // sad we have to specify this + isConstant: false, // constructors are non-const by their nature, right? + 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 _genMethodDoc( + abiDefinition: MethodAbi | FallbackAbi, + devdocIfExists: DevdocOutput | undefined, +): SolidityMethod { + const name = abiDefinition.type === 'fallback' ? '' : abiDefinition.name; + + const { parameters, methodSignature } = + abiDefinition.type === 'fallback' + ? { parameters: [], methodSignature: `${name}()` } + : _genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists); + + const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists); + + const returnType = + abiDefinition.type === 'fallback' + ? { name: '', typeDocType: TypeDocTypes.Intrinsic } + : _genMethodReturnTypeDoc(abiDefinition.outputs, methodSignature, devdocIfExists); + + const isConstant = abiDefinition.type === 'fallback' ? true : abiDefinition.constant; + // TODO: determine whether fallback functions are always constant, as coded just above + + const methodDoc: SolidityMethod = { + isConstructor: false, + name, + callPath: '', // TODO: wtf is this? + parameters, + returnType, + isConstant, + 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: DataItem[], 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: false, // TODO: wtf is this? + name, + type, + }; + + eventArgsDoc.push(eventArgDoc); + } + return eventArgsDoc; +} + +/** + * Extract documentation for each method paramater from @param params. + */ +function _genMethodParamsDoc( + name: string, + abiParams: DataItem[], + devdocIfExists: DevdocOutput | undefined, +): { parameters: Parameter[]; methodSignature: string } { + const parameters: Parameter[] = []; + let methodSignature = `${name}(`; + + for (const abiParam of abiParams) { + const parameter: Parameter = { + name: abiParam.name, + comment: '', + isOptional: false, // Unsupported in Solidity, until resolution of https://github.com/ethereum/solidity/issues/232 + type: { name: abiParam.type, typeDocType: TypeDocTypes.Intrinsic }, + }; + parameters.push(parameter); + methodSignature = `${methodSignature}${abiParam.type},`; + } + + if (methodSignature.slice(-1) === ',') { + methodSignature = methodSignature.slice(0, -1); + } + methodSignature += ')'; + + 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[], + methodSignature: string, + devdocIfExists: DevdocOutput | undefined, +): Type { + const methodReturnTypeDoc: Type = { + name: '', + typeDocType: TypeDocTypes.Intrinsic, + tupleElements: undefined, + }; + if (outputs.length > 1) { + methodReturnTypeDoc.typeDocType = TypeDocTypes.Tuple; + methodReturnTypeDoc.tupleElements = []; + for (const output of outputs) { + methodReturnTypeDoc.tupleElements.push({ name: output.name, typeDocType: TypeDocTypes.Intrinsic }); + } + } else if (outputs.length === 1) { + methodReturnTypeDoc.typeDocType = TypeDocTypes.Intrinsic; + methodReturnTypeDoc.name = outputs[0].name; + } + return methodReturnTypeDoc; +} diff --git a/packages/sol-doc/test/fixtures/contracts/TokenTransferProxy.sol b/packages/sol-doc/test/fixtures/contracts/TokenTransferProxy.sol new file mode 100644 index 000000000..44570d459 --- /dev/null +++ b/packages/sol-doc/test/fixtures/contracts/TokenTransferProxy.sol @@ -0,0 +1,115 @@ +/* + + Copyright 2018 ZeroEx Intl. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +*/ + +pragma solidity ^0.4.14; + +import { Ownable } from "zeppelin-solidity/contracts/ownership/Ownable.sol"; +import { ERC20 as Token } from "zeppelin-solidity/contracts/token/ERC20/ERC20.sol"; + +/// @title TokenTransferProxy - Transfers tokens on behalf of contracts that have been approved via decentralized governance. +/// @author Amir Bandeali - <amir@0xProject.com>, Will Warren - <will@0xProject.com> +contract TokenTransferProxy is Ownable { + + /// @dev Only authorized addresses can invoke functions with this modifier. + modifier onlyAuthorized { + require(authorized[msg.sender]); + _; + } + + modifier targetAuthorized(address target) { + require(authorized[target]); + _; + } + + modifier targetNotAuthorized(address target) { + require(!authorized[target]); + _; + } + + mapping (address => bool) public authorized; + address[] public authorities; + + event LogAuthorizedAddressAdded(address indexed target, address indexed caller); + event LogAuthorizedAddressRemoved(address indexed target, address indexed caller); + + /* + * Public functions + */ + + /// @dev Authorizes an address. + /// @param target Address to authorize. + function addAuthorizedAddress(address target) + public + onlyOwner + targetNotAuthorized(target) + { + authorized[target] = true; + authorities.push(target); + LogAuthorizedAddressAdded(target, msg.sender); + } + + /// @dev Removes authorizion of an address. + /// @param target Address to remove authorization from. + function removeAuthorizedAddress(address target) + public + onlyOwner + targetAuthorized(target) + { + delete authorized[target]; + for (uint i = 0; i < authorities.length; i++) { + if (authorities[i] == target) { + authorities[i] = authorities[authorities.length - 1]; + authorities.length -= 1; + break; + } + } + LogAuthorizedAddressRemoved(target, msg.sender); + } + + /// @dev Calls into ERC20 Token contract, invoking transferFrom. + /// @param token Address of token to transfer. + /// @param from Address to transfer token from. + /// @param to Address to transfer token to. + /// @param value Amount of token to transfer. + /// @return Success of transfer. + function transferFrom( + address token, + address from, + address to, + uint value) + public + onlyAuthorized + returns (bool) + { + return Token(token).transferFrom(from, to, value); + } + + /* + * Public constant functions + */ + + /// @dev Gets all authorized addresses. + /// @return Array of authorized addresses. + function getAuthorizedAddresses() + public + constant + returns (address[]) + { + return authorities; + } +} diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts new file mode 100644 index 000000000..7f11fcdfd --- /dev/null +++ b/packages/sol-doc/test/solidity_doc_generator_test.ts @@ -0,0 +1,76 @@ +import * as _ from 'lodash'; + +import * as chai from 'chai'; +import 'mocha'; + +import { SolidityMethod } from '@0xproject/types'; + +import { generateSolDocAsync } from '../src/solidity_doc_generator'; + +import { chaiSetup } from './util/chai_setup'; + +chaiSetup.configure(); +const expect = chai.expect; + +describe('#SolidityDocGenerator', () => { + it('should generate a doc object that matches the TokenTransferProxy fixture', async () => { + const doc = await generateSolDocAsync(['TokenTransferProxy'], `${__dirname}/../../test/fixtures/contracts`); + + expect(doc).to.not.be.undefined(); + + const tokenTransferProxyConstructorCount = 0; + const tokenTransferProxyMethodCount = 8; + const tokenTransferProxyEventCount = 3; + expect(doc.TokenTransferProxy.constructors.length).to.equal(tokenTransferProxyConstructorCount); + expect(doc.TokenTransferProxy.methods.length).to.equal(tokenTransferProxyMethodCount); + if (_.isUndefined(doc.TokenTransferProxy.events)) { + throw new Error('events should never be undefined'); + } + expect(doc.TokenTransferProxy.events.length).to.equal(tokenTransferProxyEventCount); + + const ownableConstructorCount = 1; + const ownableMethodCount = 2; + const ownableEventCount = 1; + expect(doc.Ownable.constructors.length).to.equal(ownableConstructorCount); + expect(doc.Ownable.methods.length).to.equal(ownableMethodCount); + if (_.isUndefined(doc.Ownable.events)) { + throw new Error('events should never be undefined'); + } + expect(doc.Ownable.events.length).to.equal(ownableEventCount); + + const erc20ConstructorCount = 0; + const erc20MethodCount = 6; + const erc20EventCount = 2; + expect(doc.ERC20.constructors.length).to.equal(erc20ConstructorCount); + expect(doc.ERC20.methods.length).to.equal(erc20MethodCount); + if (_.isUndefined(doc.ERC20.events)) { + throw new Error('events should never be undefined'); + } + expect(doc.ERC20.events.length).to.equal(erc20EventCount); + + const erc20BasicConstructorCount = 0; + const erc20BasicMethodCount = 3; + const erc20BasicEventCount = 1; + expect(doc.ERC20Basic.constructors.length).to.equal(erc20BasicConstructorCount); + expect(doc.ERC20Basic.methods.length).to.equal(erc20BasicMethodCount); + if (_.isUndefined(doc.ERC20Basic.events)) { + throw new Error('events should never be undefined'); + } + expect(doc.ERC20Basic.events.length).to.equal(erc20BasicEventCount); + + let addAuthorizedAddressMethod: SolidityMethod | undefined; + for (const method of doc.TokenTransferProxy.methods) { + if (method.name === 'addAuthorizedAddress') { + addAuthorizedAddressMethod = method; + } + } + expect( + addAuthorizedAddressMethod, + `method addAuthorizedAddress not found in ${JSON.stringify(doc.TokenTransferProxy.methods)}`, + ).to.not.be.undefined(); + const tokenTransferProxyAddAuthorizedAddressComment = 'Authorizes an address.'; + expect((addAuthorizedAddressMethod as SolidityMethod).comment).to.equal( + tokenTransferProxyAddAuthorizedAddressComment, + ); + }); +}); diff --git a/packages/sol-doc/test/util/chai_setup.ts b/packages/sol-doc/test/util/chai_setup.ts new file mode 100644 index 000000000..1a8733093 --- /dev/null +++ b/packages/sol-doc/test/util/chai_setup.ts @@ -0,0 +1,13 @@ +import * as chai from 'chai'; +import chaiAsPromised = require('chai-as-promised'); +import ChaiBigNumber = require('chai-bignumber'); +import * as dirtyChai from 'dirty-chai'; + +export const chaiSetup = { + configure(): void { + chai.config.includeStack = true; + chai.use(ChaiBigNumber()); + chai.use(dirtyChai); + chai.use(chaiAsPromised); + }, +}; diff --git a/packages/sol-doc/tsconfig.json b/packages/sol-doc/tsconfig.json new file mode 100644 index 000000000..2ee711adc --- /dev/null +++ b/packages/sol-doc/tsconfig.json @@ -0,0 +1,8 @@ +{ + "extends": "../../tsconfig", + "compilerOptions": { + "outDir": "lib", + "rootDir": "." + }, + "include": ["./src/**/*", "./test/**/*"] +} diff --git a/packages/sol-doc/tslint.json b/packages/sol-doc/tslint.json new file mode 100644 index 000000000..ffaefe83a --- /dev/null +++ b/packages/sol-doc/tslint.json @@ -0,0 +1,3 @@ +{ + "extends": ["@0xproject/tslint-config"] +} diff --git a/packages/testnet-faucets/src/ts/handler.ts b/packages/testnet-faucets/src/ts/handler.ts index 82e9a9494..e73eb1744 100644 --- a/packages/testnet-faucets/src/ts/handler.ts +++ b/packages/testnet-faucets/src/ts/handler.ts @@ -158,6 +158,7 @@ export class Handler { if (_.isUndefined(takerTokenIfExists)) { throw new Error(`Unsupported asset type: ${takerTokenSymbol}`); } + const makerAssetAmount = Web3Wrapper.toBaseUnitAmount(ASSET_AMOUNT, makerTokenIfExists.decimals); const takerAssetAmount = Web3Wrapper.toBaseUnitAmount(ASSET_AMOUNT, takerTokenIfExists.decimals); const makerAssetData = assetDataUtils.encodeERC20AssetData(makerTokenIfExists.address); diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts index 48a9e23d1..e2333d5d0 100644 --- a/packages/types/src/index.ts +++ b/packages/types/src/index.ts @@ -239,3 +239,226 @@ export enum StatusCodes { MethodNotAllowed = 405, GatewayTimeout = 504, } + +export interface TypeDocType { + type: TypeDocTypes; + value: string; + name: string; + types: TypeDocType[]; + typeArguments?: TypeDocType[]; + declaration: TypeDocNode; + elementType?: TypeDocType; + indexSignature?: TypeDocNode; + elements?: TupleElement[]; +} + +export interface TupleElement { + type: string; + name: string; +} + +export interface TypeDocNode { + id?: number; + name?: string; + kind?: string; + defaultValue?: string; + kindString?: string; + type?: TypeDocType; + fileName?: string; + line?: number; + comment?: TypeDocNode; + text?: string; + shortText?: string; + returns?: string; + declaration: TypeDocNode; + flags?: TypeDocFlags; + indexSignature?: TypeDocNode; + signatures?: TypeDocNode[]; + parameters?: TypeDocNode[]; + typeParameter?: TypeDocNode[]; + sources?: TypeDocNode[]; + children?: TypeDocNode[]; + groups?: TypeDocGroup[]; +} + +export interface TypeDocFlags { + isStatic?: boolean; + isOptional?: boolean; + isPublic?: boolean; + isExported?: boolean; +} + +export interface TypeDocGroup { + title: string; + children: number[]; +} + +export enum TypeDocTypes { + Intrinsic = 'intrinsic', + Reference = 'reference', + Array = 'array', + StringLiteral = 'stringLiteral', + Reflection = 'reflection', + Union = 'union', + TypeParameter = 'typeParameter', + Intersection = 'intersection', + Tuple = 'tuple', + Unknown = 'unknown', +} + +export interface CustomTypeChild { + name: string; + type?: Type; + defaultValue?: string; +} + +export interface Event { + name: string; + eventArgs: EventArg[]; +} + +export interface EventArg { + isIndexed: boolean; + name: string; + type: Type; +} + +export interface Property { + name: string; + type: Type; + source?: Source; + comment?: string; + callPath?: string; +} + +export interface BaseMethod { + isConstructor: boolean; + name: string; + returnComment?: string | undefined; + callPath: string; + parameters: Parameter[]; + returnType: Type; + comment?: string; +} + +export interface BaseFunction { + name: string; + returnComment?: string | undefined; + parameters: Parameter[]; + returnType: Type; + comment?: string; +} + +export interface TypeDefinitionByName { + [typeName: string]: CustomType; +} + +export interface DocAgnosticFormat { + [sectionName: string]: DocSection; +} + +export interface DocSection { + comment: string; + constructors: Array<TypescriptMethod | SolidityMethod>; + methods: Array<TypescriptMethod | SolidityMethod>; + properties: Property[]; + types: CustomType[]; + functions: TypescriptFunction[]; + events?: Event[]; + externalExportToLink?: ExternalExportToLink; +} + +export interface TypescriptMethod extends BaseMethod { + source?: Source; + isStatic?: boolean; + typeParameter?: TypeParameter; +} + +export interface TypescriptFunction extends BaseFunction { + source?: Source; + typeParameter?: TypeParameter; + callPath: string; +} + +export interface SolidityMethod extends BaseMethod { + isConstant?: boolean; + isPayable?: boolean; +} + +export interface Source { + fileName: string; + line: number; +} + +export interface Parameter { + name: string; + comment: string; + isOptional: boolean; + type: Type; + defaultValue?: string; +} + +export interface TypeParameter { + name: string; + type: Type; +} + +export interface Type { + name: string; + typeDocType: TypeDocTypes; + value?: string; + isExportedClassReference?: boolean; + typeArguments?: Type[]; + elementType?: ElementType; + types?: Type[]; + method?: TypescriptMethod; + indexSignature?: IndexSignature; + externalLink?: string; + tupleElements?: Type[]; +} + +export interface ElementType { + name: string; + typeDocType: TypeDocTypes; +} + +export interface IndexSignature { + keyName: string; + keyType: Type; + valueName: string; +} + +export interface CustomType { + name: string; + kindString: string; + type?: Type; + method?: TypescriptMethod; + indexSignature?: IndexSignature; + defaultValue?: string; + comment?: string; + children?: CustomTypeChild[]; +} +export interface GeneratedDocJson { + version: string; + metadata: Metadata; + typedocJson: TypeDocNode; +} + +export interface ExportNameToTypedocNames { + [exportName: string]: string[]; +} + +export interface ExternalTypeToLink { + [externalTypeName: string]: string; +} + +export interface ExternalExportToLink { + [externalExport: string]: string; +} + +export interface Metadata { + exportPathToTypedocNames: ExportNameToTypedocNames; + exportPathOrder: string[]; + externalTypeToLink: ExternalTypeToLink; + externalExportToLink: ExternalExportToLink; +} diff --git a/packages/typescript-typings/types/solc/index.d.ts b/packages/typescript-typings/types/solc/index.d.ts index 571bae101..f4c05cd7c 100644 --- a/packages/typescript-typings/types/solc/index.d.ts +++ b/packages/typescript-typings/types/solc/index.d.ts @@ -1,4 +1,6 @@ declare module 'solc' { + export { ErrorType, ErrorSeverity, SolcError, StandardContractOutput, StandardOutput } from 'ethereum-types'; + import { SolcError } from 'ethereum-types'; export interface ContractCompilationResult { srcmap: string; srcmapRuntime: string; @@ -87,62 +89,6 @@ declare module 'solc' { }; settings: CompilerSettings; } - export type ErrorType = - | 'JSONError' - | 'IOError' - | 'ParserError' - | 'DocstringParsingError' - | 'SyntaxError' - | 'DeclarationError' - | 'TypeError' - | 'UnimplementedFeatureError' - | 'InternalCompilerError' - | 'Exception' - | 'CompilerError' - | 'FatalError' - | 'Warning'; - export type ErrorSeverity = 'error' | 'warning'; - export interface Error { - sourceLocation?: { - file: string; - start: number; - end: number; - }; - type: ErrorType; - component: 'general' | 'ewasm'; - severity: ErrorSeverity; - message: string; - formattedMessage?: string; - } - import { ContractAbi } from 'ethereum-types'; - export interface StandardContractOutput { - abi: ContractAbi; - evm: { - bytecode: { - object: string; - sourceMap: string; - }; - deployedBytecode: { - object: string; - sourceMap: string; - }; - }; - } - export interface StandardOutput { - errors: Error[]; - sources: { - [fileName: string]: { - id: number; - ast?: object; - legacyAST?: object; - }; - }; - contracts: { - [fileName: string]: { - [contractName: string]: StandardContractOutput; - }; - }; - } export interface SolcInstance { compile( sources: InputSources, @@ -151,6 +97,9 @@ declare module 'solc' { ): CompilationResult; compileStandardWrapper(input: string, findImports: (importPath: string) => ImportContents): string; } - export function loadRemoteVersion(versionName: string, cb: (err: Error | null, res?: SolcInstance) => void): void; + export function loadRemoteVersion( + versionName: string, + cb: (err: SolcError | null, res?: SolcInstance) => void, + ): void; export function setupMethods(solcBin: any): SolcInstance; } |