diff options
Diffstat (limited to 'packages/utils')
| -rw-r--r-- | packages/utils/CHANGELOG.json | 9 | ||||
| -rw-r--r-- | packages/utils/package.json | 2 | ||||
| -rw-r--r-- | packages/utils/src/abi_decoder.ts | 124 | ||||
| -rw-r--r-- | packages/utils/src/address_utils.ts | 11 | ||||
| -rw-r--r-- | packages/utils/src/index.ts | 2 | ||||
| -rw-r--r-- | packages/utils/src/random.ts | 16 | ||||
| -rw-r--r-- | packages/utils/src/types.ts | 19 | ||||
| -rw-r--r-- | packages/utils/test/abi_decoder_test.ts | 50 |
8 files changed, 214 insertions, 19 deletions
diff --git a/packages/utils/CHANGELOG.json b/packages/utils/CHANGELOG.json index 9ce2a4c52..95f61a43c 100644 --- a/packages/utils/CHANGELOG.json +++ b/packages/utils/CHANGELOG.json @@ -1,5 +1,14 @@ [ { + "version": "4.1.0", + "changes": [ + { + "note": "Added method decoding to AbiDecoder", + "pr": 1569 + } + ] + }, + { "version": "4.0.4", "changes": [ { diff --git a/packages/utils/package.json b/packages/utils/package.json index 86fecbc7c..895560961 100644 --- a/packages/utils/package.json +++ b/packages/utils/package.json @@ -14,7 +14,7 @@ "lint": "tslint --format stylish --project .", "test": "yarn run_mocha", "test:circleci": "yarn test:coverage", - "run_mocha": "mocha --require source-map-support/register --require make-promises-safe lib/test/**/*_test.js --bail --exit", + "run_mocha": "mocha --require source-map-support/register --require make-promises-safe 'lib/test/**/*_test.js' 'lib/test/*_test.js' --bail --exit", "test:coverage": "nyc npm run test --all && yarn coverage:report:lcov", "coverage:report:lcov": "nyc report --reporter=text-lcov > coverage/lcov.info" }, diff --git a/packages/utils/src/abi_decoder.ts b/packages/utils/src/abi_decoder.ts index 28b6418d8..b764e45b8 100644 --- a/packages/utils/src/abi_decoder.ts +++ b/packages/utils/src/abi_decoder.ts @@ -6,28 +6,49 @@ import { EventParameter, LogEntry, LogWithDecodedArgs, + MethodAbi, RawLog, SolidityTypes, } from 'ethereum-types'; import * as ethers from 'ethers'; import * as _ from 'lodash'; +import { AbiEncoder } from '.'; import { addressUtils } from './address_utils'; import { BigNumber } from './configured_bignumber'; +import { DecodedCalldata, SelectorToFunctionInfo } from './types'; /** * AbiDecoder allows you to decode event logs given a set of supplied contract ABI's. It takes the contract's event * signature from the ABI and attempts to decode the logs using it. */ export class AbiDecoder { - private readonly _methodIds: { [signatureHash: string]: { [numIndexedArgs: number]: EventAbi } } = {}; + private readonly _eventIds: { [signatureHash: string]: { [numIndexedArgs: number]: EventAbi } } = {}; + private readonly _selectorToFunctionInfo: SelectorToFunctionInfo = {}; + /** + * Retrieves the function selector from calldata. + * @param calldata hex-encoded calldata. + * @return hex-encoded function selector. + */ + private static _getFunctionSelector(calldata: string): string { + const functionSelectorLength = 10; + if (!calldata.startsWith('0x') || calldata.length < functionSelectorLength) { + throw new Error( + `Malformed calldata. Must include a hex prefix '0x' and 4-byte function selector. Got '${calldata}'`, + ); + } + const functionSelector = calldata.substr(0, functionSelectorLength); + return functionSelector; + } /** * Instantiate an AbiDecoder * @param abiArrays An array of contract ABI's * @return AbiDecoder instance */ constructor(abiArrays: AbiDefinition[][]) { - _.forEach(abiArrays, this.addABI.bind(this)); + _.each(abiArrays, abi => { + this.addABI(abi); + }); } /** * Attempt to decode a log given the ABI's the AbiDecoder knows about. @@ -35,12 +56,12 @@ export class AbiDecoder { * @return The decoded log if the requisite ABI was available. Otherwise the log unaltered. */ public tryToDecodeLogOrNoop<ArgsType extends DecodedLogArgs>(log: LogEntry): LogWithDecodedArgs<ArgsType> | RawLog { - const methodId = log.topics[0]; + const eventId = log.topics[0]; const numIndexedArgs = log.topics.length - 1; - if (_.isUndefined(this._methodIds[methodId]) || _.isUndefined(this._methodIds[methodId][numIndexedArgs])) { + if (_.isUndefined(this._eventIds[eventId]) || _.isUndefined(this._eventIds[eventId][numIndexedArgs])) { return log; } - const event = this._methodIds[methodId][numIndexedArgs]; + const event = this._eventIds[eventId][numIndexedArgs]; const ethersInterface = new ethers.utils.Interface([event]); const decodedParams: DecodedLogArgs = {}; let topicsIndex = 1; @@ -89,25 +110,94 @@ export class AbiDecoder { } } /** - * Add additional ABI definitions to the AbiDecoder - * @param abiArray An array of ABI definitions to add to the AbiDecoder + * Decodes calldata for a known ABI. + * @param calldata hex-encoded calldata. + * @param contractName used to disambiguate similar ABI's (optional). + * @return Decoded calldata. Includes: function name and signature, along with the decoded arguments. */ - public addABI(abiArray: AbiDefinition[]): void { + public decodeCalldataOrThrow(calldata: string, contractName?: string): DecodedCalldata { + const functionSelector = AbiDecoder._getFunctionSelector(calldata); + const candidateFunctionInfos = this._selectorToFunctionInfo[functionSelector]; + if (_.isUndefined(candidateFunctionInfos)) { + throw new Error(`No functions registered for selector '${functionSelector}'`); + } + const functionInfo = _.find(candidateFunctionInfos, candidateFunctionInfo => { + return ( + _.isUndefined(contractName) || _.toLower(contractName) === _.toLower(candidateFunctionInfo.contractName) + ); + }); + if (_.isUndefined(functionInfo)) { + throw new Error( + `No function registered with selector ${functionSelector} and contract name ${contractName}.`, + ); + } else if (_.isUndefined(functionInfo.abiEncoder)) { + throw new Error( + `Function ABI Encoder is not defined, for function registered with selector ${functionSelector} and contract name ${contractName}.`, + ); + } + const functionName = functionInfo.abiEncoder.getDataItem().name; + const functionSignature = functionInfo.abiEncoder.getSignatureType(); + const functionArguments = functionInfo.abiEncoder.decode(calldata); + const decodedCalldata = { + functionName, + functionSignature, + functionArguments, + }; + return decodedCalldata; + } + /** + * Adds a set of ABI definitions, after which calldata and logs targeting these ABI's can be decoded. + * Additional properties can be included to disambiguate similar ABI's. For example, if two functions + * have the same signature but different parameter names, then their ABI definitions can be disambiguated + * by specifying a contract name. + * @param abiDefinitions ABI definitions for a given contract. + * @param contractName Name of contract that encapsulates the ABI definitions (optional). + * This can be used when decoding calldata to disambiguate methods with + * the same signature but different parameter names. + */ + public addABI(abiArray: AbiDefinition[], contractName?: string): void { if (_.isUndefined(abiArray)) { return; } const ethersInterface = new ethers.utils.Interface(abiArray); _.map(abiArray, (abi: AbiDefinition) => { - if (abi.type === AbiType.Event) { - // tslint:disable-next-line:no-unnecessary-type-assertion - const eventAbi = abi as EventAbi; - const topic = ethersInterface.events[eventAbi.name].topic; - const numIndexedArgs = _.reduce(eventAbi.inputs, (sum, input) => (input.indexed ? sum + 1 : sum), 0); - this._methodIds[topic] = { - ...this._methodIds[topic], - [numIndexedArgs]: eventAbi, - }; + switch (abi.type) { + case AbiType.Event: + // tslint:disable-next-line:no-unnecessary-type-assertion + this._addEventABI(abi as EventAbi, ethersInterface); + break; + + case AbiType.Function: + // tslint:disable-next-line:no-unnecessary-type-assertion + this._addMethodABI(abi as MethodAbi, contractName); + break; + + default: + // ignore other types + break; } }); } + private _addEventABI(eventAbi: EventAbi, ethersInterface: ethers.utils.Interface): void { + const topic = ethersInterface.events[eventAbi.name].topic; + const numIndexedArgs = _.reduce(eventAbi.inputs, (sum, input) => (input.indexed ? sum + 1 : sum), 0); + this._eventIds[topic] = { + ...this._eventIds[topic], + [numIndexedArgs]: eventAbi, + }; + } + private _addMethodABI(methodAbi: MethodAbi, contractName?: string): void { + const abiEncoder = new AbiEncoder.Method(methodAbi); + const functionSelector = abiEncoder.getSelector(); + if (!(functionSelector in this._selectorToFunctionInfo)) { + this._selectorToFunctionInfo[functionSelector] = []; + } + // Recored a copy of this ABI for each deployment + const functionSignature = abiEncoder.getSignature(); + this._selectorToFunctionInfo[functionSelector].push({ + functionSignature, + abiEncoder, + contractName, + }); + } } diff --git a/packages/utils/src/address_utils.ts b/packages/utils/src/address_utils.ts index 1fc960408..361e35cd8 100644 --- a/packages/utils/src/address_utils.ts +++ b/packages/utils/src/address_utils.ts @@ -1,7 +1,9 @@ -import { addHexPrefix, stripHexPrefix } from 'ethereumjs-util'; +import { addHexPrefix, sha3, stripHexPrefix } from 'ethereumjs-util'; import * as jsSHA3 from 'js-sha3'; import * as _ from 'lodash'; +import { generatePseudoRandom256BitNumber } from './random'; + const BASIC_ADDRESS_REGEX = /^(0x)?[0-9a-f]{40}$/i; const SAME_CASE_ADDRESS_REGEX = /^(0x)?([0-9a-f]{40}|[0-9A-F]{40})$/; const ADDRESS_LENGTH = 40; @@ -43,4 +45,11 @@ export const addressUtils = { padZeros(address: string): string { return addHexPrefix(_.padStart(stripHexPrefix(address), ADDRESS_LENGTH, '0')); }, + generatePseudoRandomAddress(): string { + const randomBigNum = generatePseudoRandom256BitNumber(); + const randomBuff = sha3(randomBigNum.toString()); + const addressLengthInBytes = 20; + const randomAddress = `0x${randomBuff.slice(0, addressLengthInBytes).toString('hex')}`; + return randomAddress; + }, }; diff --git a/packages/utils/src/index.ts b/packages/utils/src/index.ts index 082aff6bb..f9c2693fe 100644 --- a/packages/utils/src/index.ts +++ b/packages/utils/src/index.ts @@ -11,3 +11,5 @@ export { errorUtils } from './error_utils'; export { fetchAsync } from './fetch_async'; export { signTypedDataUtils } from './sign_typed_data_utils'; export import AbiEncoder = require('./abi_encoder'); +export * from './types'; +export { generatePseudoRandom256BitNumber } from './random'; diff --git a/packages/utils/src/random.ts b/packages/utils/src/random.ts new file mode 100644 index 000000000..69243bab8 --- /dev/null +++ b/packages/utils/src/random.ts @@ -0,0 +1,16 @@ +import { BigNumber } from './configured_bignumber'; + +const MAX_DIGITS_IN_UNSIGNED_256_INT = 78; + +/** + * Generates a pseudo-random 256-bit number. + * @return A pseudo-random 256-bit number. + */ +export function generatePseudoRandom256BitNumber(): BigNumber { + // BigNumber.random returns a pseudo-random number between 0 & 1 with a passed in number of decimal places. + // Source: https://mikemcl.github.io/bignumber.js/#random + const randomNumber = BigNumber.random(MAX_DIGITS_IN_UNSIGNED_256_INT); + const factor = new BigNumber(10).pow(MAX_DIGITS_IN_UNSIGNED_256_INT - 1); + const randomNumberScaledTo256Bits = randomNumber.times(factor).integerValue(); + return randomNumberScaledTo256Bits; +} diff --git a/packages/utils/src/types.ts b/packages/utils/src/types.ts new file mode 100644 index 000000000..32e11efa2 --- /dev/null +++ b/packages/utils/src/types.ts @@ -0,0 +1,19 @@ +import { AbiEncoder } from '.'; + +export interface FunctionInfo { + functionSignature: string; + contractName?: string; + contractAddress?: string; + networkId?: number; + abiEncoder?: AbiEncoder.Method; +} + +export interface SelectorToFunctionInfo { + [index: string]: FunctionInfo[]; +} + +export interface DecodedCalldata { + functionName: string; + functionSignature: string; + functionArguments: any; +} diff --git a/packages/utils/test/abi_decoder_test.ts b/packages/utils/test/abi_decoder_test.ts new file mode 100644 index 000000000..81fed1060 --- /dev/null +++ b/packages/utils/test/abi_decoder_test.ts @@ -0,0 +1,50 @@ +import * as chai from 'chai'; +import { MethodAbi } from 'ethereum-types'; +import 'mocha'; + +import { AbiDecoder, AbiEncoder } from '../src'; + +import { chaiSetup } from './utils/chai_setup'; + +chaiSetup.configure(); +const expect = chai.expect; + +describe('AbiDecoder', () => { + it('should successfully add a new ABI and decode calldata for it', async () => { + // Add new ABI + const abi: MethodAbi = { + name: 'foobar', + type: 'function', + inputs: [ + { + name: 'testAddress', + type: 'address', + }, + ], + outputs: [ + { + name: 'butter', + type: 'string', + }, + ], + constant: false, + payable: false, + stateMutability: 'pure', + }; + const contractName = 'newContract'; + const testAddress = '0x0001020304050607080900010203040506070809'; + const abiDecoder = new AbiDecoder([]); + abiDecoder.addABI([abi], contractName); + // Create some tx data + const foobarEncoder = new AbiEncoder.Method(abi); + const foobarSignature = foobarEncoder.getSignature(); + const foobarTxData = foobarEncoder.encode([testAddress]); + // Decode tx data using contract name + const decodedTxData = abiDecoder.decodeCalldataOrThrow(foobarTxData, contractName); + const expectedFunctionName = abi.name; + const expectedFunctionArguments = { testAddress }; + expect(decodedTxData.functionName).to.be.equal(expectedFunctionName); + expect(decodedTxData.functionSignature).to.be.equal(foobarSignature); + expect(decodedTxData.functionArguments).to.be.deep.equal(expectedFunctionArguments); + }); +}); |