diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 1d66d745..ba367396 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -12,7 +12,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - node-version: [10.x, 12.x, 13.x] + node-version: [10.x, 12.x, 13.x, 14.x] steps: - name: Use Node.js ${{ matrix.node-version }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 440e84a1..70d5f8e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,140 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) (modification: no type change headlines) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html). +## [7.0.0] - 2020-04-30 + +This release comes with significant changes to the API, updated versions of +the core crypto libraries and substantial developer improvements in the form +of a refactored test suite and API documentation. + +### API Changes + +Changes to the API have been discussed in Issue +[#172](https://github.com/ethereumjs/ethereumjs-util/issues/172) and are +guided by the principles of: + +- Make the API more typestrict +- Be less ambiguous regarding accepted values +- Avoid implicit type conversions +- Be more explicit on wrong input (just: throw) + +While the implemented changes come with some additional need for manual type +conversions depending on the usage context, they should finally lead to +cleaner usage patterns on the cosuming side and a more predictable, robust and +less error-prone control flow. + +Some note: for methods where `Buffer` usage is now enforced you can use the +`Bytes.toBuffer()` method for conversion. + +#### Account Module + +##### Enforced Hex Prefixing for Address Strings + +PR: [#241](https://github.com/ethereumjs/ethereumjs-util/pull/241) + +Hex prefixing is now enforced for all address string inputs and functions +will throw if a non-hex string is provided: + +- `Account.isValidAddress()` +- `Account.isZeroAddress()` +- `Account.toChecksumAddress()` +- `Account.isValidChecksumAddress()` + +The `Account.isPrecompile()` method was removed from the code base, +PR [#242](https://github.com/ethereumjs/ethereumjs-util/pull/242) + +##### Enforce Buffer Inputs for Account Methods + +PR: [#245](https://github.com/ethereumjs/ethereumjs-util/pull/245) + +Implicit `Buffer` conversions for the following methods have been removed +and `Buffer` inputs are now enforced: + +- `Account.generateAddress()` +- `Account.generateAddress2()` +- `Account.pubToAddress()` +- `AccountprivateToPublic()` +- `AccountimportPublic()` + +#### Bytes Module + +##### Typestrict Methods and Type-Explicit Method Split-Up + +PR: [#244](https://github.com/ethereumjs/ethereumjs-util/pull/244) + +- Enforced `Buffer` input for `Bytes.setLengthLeft()`, `Bytes.setLengthRight()` +- `Bytes.setLength()` has been removed (alias for `Bytes.setLengthLeft()`) +- `Bytes.stripZeros()` has been removed (alias for `Bytes.unPad()`) +- `Bytes.unpad` has been split up into: + - `Bytes.unpadBuffer()` + - `Bytes.unpadHexString()` + - `Bytes.unpadArray()` + +#### Hash Module + +##### Typestrict Methods and Type-Explicit Method Split-Up + +PR [#247](https://github.com/ethereumjs/ethereumjs-util/pull/247) + +The following methods are now `Buffer`-only: + +- `Hash.keccak()` +- `Hash.keccak256()` +- `Hash.sha256()` +- `Hash.ripemd160()` + +`Hash.keccak()` gets the following additional convenience methods: + +- `Hash.keccakFromString()` +- `Hash.keccakFromHexString()` (hex string enforced) + `Hash.keccakFromArray()` + +`Hash.sha256()` gets the following additional convenience methods: + +- `Hash.sha256FromString()` +- `Hash.sha256FromArray()` + +`Hash.ripemd160()` gets the following additional convenience methods: + +- `Hash.ripemd160FromString()` +- `Hash.ripemd160FromArray()` + +#### Other Breaking Changes + +- Added support for Node 14, + PR [#249](https://github.com/ethereumjs/ethereumjs-util/pull/249) +- Dropped support for Node `8` along + PR [#228](https://github.com/ethereumjs/ethereumjs-util/pull/228) +- Updated `BN.js` library re-export from `4.x` to `5.x`, + PR [#249], https://github.com/ethereumjs/ethereumjs-util/pull/249 +- Removed `secp2561` re-export (use methods provided or import directly), + PR [#228](https://github.com/ethereumjs/ethereumjs-util/pull/228) + +### Cryto Library Updates: Keccak, secp2561 + +`Keccak` dependency has been updated from `2.1.0` to `3.0.0`. This version +comes with prebuilds for Linux, MacOS and Windows so most users won't need +to have `node-gyp` run on installation. + +The version update also brings in feature compatibility with newer Node.js +versions. + +The `secp2561` ECDSA dependency has been updated from `3.0.1` to `4.0.1`. + +### Developer Improvements + +- Refactored test suite (module split-up, headless Firefox and Chrome), + PR [#231](https://github.com/ethereumjs/ethereumjs-util/pull/231) +- Moved CI from Travis to GitHub Actions, + PR [#231](https://github.com/ethereumjs/ethereumjs-util/pull/231) +- Improved and updated `TypeDoc` API documentation, + PR [#232](https://github.com/ethereumjs/ethereumjs-util/pull/232) and + PR [#236](https://github.com/ethereumjs/ethereumjs-util/pull/236) +- Basic API tests for re-exports (BN.js, RLP, ethjsUtil), + PR [#235](https://github.com/ethereumjs/ethereumjs-util/pull/235) + +[7.0.0]: https://github.com/ethereumjs/ethereumjs-util/compare/v6.2.0...v7.0.0 + ## [6.2.0] - 2019-11-06 This release comes with a new file structure, related functionality is now broken diff --git a/README.md b/README.md index b8fff2fa..6c80f95d 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ assert.equal(new BN('dead', 16).add(new BN('101010', 2)), 57047) - Signing, signature validation, conversion, recovery - [externals](docs/modules/_externals_.md) - Helper methods from `ethjs-util` - - Re-exports of `BN`, `rlp`, `secp256k1` + - Re-exports of `BN`, `rlp` ### ethjs-util methods @@ -72,7 +72,6 @@ Additionally `ethereumjs-util` re-exports a few commonly-used libraries. These i - `BN` ([bn.js](https://github.com/indutny/bn.js)) - `rlp` ([rlp](https://github.com/ethereumjs/rlp)) -- `secp256k1` ([secp256k1](https://github.com/cryptocoinjs/secp256k1-node/)) # EthereumJS diff --git a/docs/README.md b/docs/README.md index 32867b8b..5d7c9d69 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,5 +11,6 @@ * ["constants"](modules/_constants_.md) * ["externals"](modules/_externals_.md) * ["hash"](modules/_hash_.md) +* ["helpers"](modules/_helpers_.md) * ["object"](modules/_object_.md) * ["signature"](modules/_signature_.md) diff --git a/docs/interfaces/_signature_.ecdsasignature.md b/docs/interfaces/_signature_.ecdsasignature.md index 428fbc16..d7ec8c62 100644 --- a/docs/interfaces/_signature_.ecdsasignature.md +++ b/docs/interfaces/_signature_.ecdsasignature.md @@ -20,7 +20,7 @@ • **r**: *Buffer* -*Defined in [signature.ts:8](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L8)* +*Defined in [signature.ts:9](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L9)* ___ @@ -28,7 +28,7 @@ ___ • **s**: *Buffer* -*Defined in [signature.ts:9](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L9)* +*Defined in [signature.ts:10](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L10)* ___ @@ -36,4 +36,4 @@ ___ • **v**: *number* -*Defined in [signature.ts:7](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L7)* +*Defined in [signature.ts:8](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L8)* diff --git a/docs/modules/_account_.md b/docs/modules/_account_.md index 720a3c3b..b7a054eb 100644 --- a/docs/modules/_account_.md +++ b/docs/modules/_account_.md @@ -13,7 +13,6 @@ * [generateAddress](_account_.md#const-generateaddress) * [generateAddress2](_account_.md#const-generateaddress2) * [importPublic](_account_.md#const-importpublic) -* [isPrecompiled](_account_.md#const-isprecompiled) * [isValidAddress](_account_.md#const-isvalidaddress) * [isValidChecksumAddress](_account_.md#const-isvalidchecksumaddress) * [isValidPrivate](_account_.md#const-isvalidprivate) @@ -31,7 +30,7 @@ • **publicToAddress**: *pubToAddress* = pubToAddress -*Defined in [account.ts:163](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L163)* +*Defined in [account.ts:160](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L160)* ## Functions @@ -39,7 +38,7 @@ ▸ **generateAddress**(`from`: Buffer, `nonce`: Buffer): *Buffer* -*Defined in [account.ts:75](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L75)* +*Defined in [account.ts:82](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L82)* Generates an address of a newly created contract. @@ -56,9 +55,9 @@ ___ ### `Const` generateAddress2 -▸ **generateAddress2**(`from`: Buffer | string, `salt`: Buffer | string, `initCode`: Buffer | string): *Buffer* +▸ **generateAddress2**(`from`: Buffer, `salt`: Buffer, `initCode`: Buffer): *Buffer* -*Defined in [account.ts:95](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L95)* +*Defined in [account.ts:103](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L103)* Generates an address for a contract created using CREATE2. @@ -66,9 +65,9 @@ Generates an address for a contract created using CREATE2. Name | Type | Description | ------ | ------ | ------ | -`from` | Buffer | string | The address which is creating this new address | -`salt` | Buffer | string | A salt | -`initCode` | Buffer | string | The init code of the contract being created | +`from` | Buffer | The address which is creating this new address | +`salt` | Buffer | A salt | +`initCode` | Buffer | The init code of the contract being created | **Returns:** *Buffer* @@ -78,7 +77,7 @@ ___ ▸ **importPublic**(`publicKey`: Buffer): *Buffer* -*Defined in [account.ts:186](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L186)* +*Defined in [account.ts:183](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L183)* Converts a public key to the Ethereum format. @@ -92,29 +91,11 @@ Name | Type | ___ -### `Const` isPrecompiled - -▸ **isPrecompiled**(`address`: Buffer | string): *boolean* - -*Defined in [account.ts:117](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L117)* - -Returns true if the supplied address belongs to a precompiled account (Byzantium). - -**Parameters:** - -Name | Type | ------- | ------ | -`address` | Buffer | string | - -**Returns:** *boolean* - -___ - ### `Const` isValidAddress -▸ **isValidAddress**(`address`: string): *boolean* +▸ **isValidAddress**(`hexAddress`: string): *boolean* -*Defined in [account.ts:20](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L20)* +*Defined in [account.ts:21](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L21)* Checks if the address is a valid. Accepts checksummed addresses too. @@ -122,7 +103,7 @@ Checks if the address is a valid. Accepts checksummed addresses too. Name | Type | ------ | ------ | -`address` | string | +`hexAddress` | string | **Returns:** *boolean* @@ -130,9 +111,9 @@ ___ ### `Const` isValidChecksumAddress -▸ **isValidChecksumAddress**(`address`: string, `eip1191ChainId?`: undefined | number): *boolean* +▸ **isValidChecksumAddress**(`hexAddress`: string, `eip1191ChainId?`: undefined | number): *boolean* -*Defined in [account.ts:66](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L66)* +*Defined in [account.ts:70](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L70)* Checks if the address is a valid checksummed address. @@ -142,7 +123,7 @@ See toChecksumAddress' documentation for details about the eip1191ChainId parame Name | Type | ------ | ------ | -`address` | string | +`hexAddress` | string | `eip1191ChainId?` | undefined | number | **Returns:** *boolean* @@ -153,7 +134,7 @@ ___ ▸ **isValidPrivate**(`privateKey`: Buffer): *boolean* -*Defined in [account.ts:125](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L125)* +*Defined in [account.ts:121](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L121)* Checks if the private key satisfies the rules of the curve secp256k1. @@ -171,7 +152,7 @@ ___ ▸ **isValidPublic**(`publicKey`: Buffer, `sanitize`: boolean): *boolean* -*Defined in [account.ts:135](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L135)* +*Defined in [account.ts:131](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L131)* Checks if the public key satisfies the rules of the curve secp256k1 and the requirements of Ethereum. @@ -189,9 +170,9 @@ ___ ### `Const` isZeroAddress -▸ **isZeroAddress**(`address`: string): *boolean* +▸ **isZeroAddress**(`hexAddress`: string): *boolean* -*Defined in [account.ts:27](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L27)* +*Defined in [account.ts:29](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L29)* Checks if a given address is a zero address. @@ -199,7 +180,7 @@ Checks if a given address is a zero address. Name | Type | ------ | ------ | -`address` | string | +`hexAddress` | string | **Returns:** *boolean* @@ -209,7 +190,7 @@ ___ ▸ **privateToAddress**(`privateKey`: Buffer): *Buffer* -*Defined in [account.ts:169](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L169)* +*Defined in [account.ts:166](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L166)* Returns the ethereum address of a given private key. @@ -227,7 +208,7 @@ ___ ▸ **privateToPublic**(`privateKey`: Buffer): *Buffer* -*Defined in [account.ts:177](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L177)* +*Defined in [account.ts:174](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L174)* Returns the ethereum public key of a given private key. @@ -245,7 +226,7 @@ ___ ▸ **pubToAddress**(`pubKey`: Buffer, `sanitize`: boolean): *Buffer* -*Defined in [account.ts:154](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L154)* +*Defined in [account.ts:151](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L151)* Returns the ethereum address of a given public key. Accepts "Ethereum public keys" and SEC1 encoded keys. @@ -263,9 +244,9 @@ ___ ### `Const` toChecksumAddress -▸ **toChecksumAddress**(`address`: string, `eip1191ChainId?`: undefined | number): *string* +▸ **toChecksumAddress**(`hexAddress`: string, `eip1191ChainId?`: undefined | number): *string* -*Defined in [account.ts:42](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L42)* +*Defined in [account.ts:45](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L45)* Returns a checksummed address. @@ -280,7 +261,7 @@ used variation in Ethereum was without the chainId. This may change in the futur Name | Type | ------ | ------ | -`address` | string | +`hexAddress` | string | `eip1191ChainId?` | undefined | number | **Returns:** *string* @@ -291,7 +272,7 @@ ___ ▸ **zeroAddress**(): *string* -*Defined in [account.ts:11](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L11)* +*Defined in [account.ts:12](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/account.ts#L12)* Returns a zero address. diff --git a/docs/modules/_bytes_.md b/docs/modules/_bytes_.md index 14cb64bc..9fb775c1 100644 --- a/docs/modules/_bytes_.md +++ b/docs/modules/_bytes_.md @@ -4,11 +4,6 @@ ## Index -### Variables - -* [setLength](_bytes_.md#const-setlength) -* [stripZeros](_bytes_.md#const-stripzeros) - ### Functions * [addHexPrefix](_bytes_.md#const-addhexprefix) @@ -20,32 +15,18 @@ * [setLengthRight](_bytes_.md#const-setlengthright) * [toBuffer](_bytes_.md#const-tobuffer) * [toUnsigned](_bytes_.md#const-tounsigned) -* [unpad](_bytes_.md#const-unpad) +* [unpadArray](_bytes_.md#const-unpadarray) +* [unpadBuffer](_bytes_.md#const-unpadbuffer) +* [unpadHexString](_bytes_.md#const-unpadhexstring) * [zeros](_bytes_.md#const-zeros) -## Variables - -### `Const` setLength - -• **setLength**: *setLengthLeft* = setLengthLeft - -*Defined in [bytes.ts:37](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L37)* - -___ - -### `Const` stripZeros - -• **stripZeros**: *unpad* = unpad - -*Defined in [bytes.ts:64](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L64)* - ## Functions ### `Const` addHexPrefix ▸ **addHexPrefix**(`str`: string): *string* -*Defined in [bytes.ts:135](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L135)* +*Defined in [bytes.ts:176](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L176)* Adds "0x" to a given `String` if it does not already start with "0x". @@ -63,7 +44,7 @@ ___ ▸ **baToJSON**(`ba`: any): *any* -*Defined in [bytes.ts:148](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L148)* +*Defined in [bytes.ts:189](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L189)* Converts a `Buffer` or `Array` to JSON. @@ -83,7 +64,7 @@ ___ ▸ **bufferToHex**(`buf`: Buffer): *string* -*Defined in [bytes.ts:111](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L111)* +*Defined in [bytes.ts:152](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L152)* Converts a `Buffer` into a `0x`-prefixed hex `String`. @@ -101,7 +82,7 @@ ___ ▸ **bufferToInt**(`buf`: Buffer): *number* -*Defined in [bytes.ts:103](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L103)* +*Defined in [bytes.ts:144](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L144)* Converts a `Buffer` to a `Number`. @@ -119,7 +100,7 @@ ___ ▸ **fromSigned**(`num`: Buffer): *BN* -*Defined in [bytes.ts:120](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L120)* +*Defined in [bytes.ts:161](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L161)* Interprets a `Buffer` as a signed integer and returns a `BN`. Assumes 256-bit numbers. @@ -135,46 +116,45 @@ ___ ### `Const` setLengthLeft -▸ **setLengthLeft**(`msg`: any, `length`: number, `right`: boolean): *any* +▸ **setLengthLeft**(`msg`: Buffer, `length`: number): *Buffer‹›* *Defined in [bytes.ts:20](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L20)* -Left Pads an `Array` or `Buffer` with leading zeros till it has `length` bytes. +Left Pads a `Buffer` with leading zeros till it has `length` bytes. Or it truncates the beginning if it exceeds. **Parameters:** -Name | Type | Default | Description | ------- | ------ | ------ | ------ | -`msg` | any | - | the value to pad (Buffer|Array) | -`length` | number | - | the number of bytes the output should be | -`right` | boolean | false | whether to start padding form the left or right | +Name | Type | Description | +------ | ------ | ------ | +`msg` | Buffer | the value to pad (Buffer) | +`length` | number | the number of bytes the output should be | -**Returns:** *any* +**Returns:** *Buffer‹›* -(Buffer|Array) +(Buffer) ___ ### `Const` setLengthRight -▸ **setLengthRight**(`msg`: any, `length`: number): *any* +▸ **setLengthRight**(`msg`: Buffer, `length`: number): *Buffer‹›* -*Defined in [bytes.ts:46](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L46)* +*Defined in [bytes.ts:32](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L32)* -Right Pads an `Array` or `Buffer` with leading zeros till it has `length` bytes. -Or it truncates the beginning if it exceeds. +Right Pads a `Buffer` with trailing zeros till it has `length` bytes. +it truncates the end if it exceeds. **Parameters:** Name | Type | Description | ------ | ------ | ------ | -`msg` | any | the value to pad (Buffer|Array) | +`msg` | Buffer | the value to pad (Buffer) | `length` | number | the number of bytes the output should be | -**Returns:** *any* +**Returns:** *Buffer‹›* -(Buffer|Array) +(Buffer) ___ @@ -182,7 +162,7 @@ ___ ▸ **toBuffer**(`v`: any): *Buffer* -*Defined in [bytes.ts:70](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L70)* +*Defined in [bytes.ts:111](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L111)* Attempts to turn a value into a `Buffer`. As input it supports `Buffer`, `String`, `Number`, null/undefined, `BN` and other objects with a `toArray()` method. @@ -200,7 +180,7 @@ ___ ▸ **toUnsigned**(`num`: BN): *Buffer* -*Defined in [bytes.ts:128](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L128)* +*Defined in [bytes.ts:169](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L169)* Converts a `BN` to an unsigned integer and returns it as a `Buffer`. Assumes 256-bit numbers. @@ -214,23 +194,63 @@ Name | Type | Description | ___ -### `Const` unpad +### `Const` unpadArray -▸ **unpad**(`a`: any): *any* +▸ **unpadArray**(`a`: number[]): *number[]* -*Defined in [bytes.ts:55](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L55)* +*Defined in [bytes.ts:77](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L77)* -Trims leading zeros from a `Buffer` or an `Array`. +Trims leading zeros from an `Array` (of numbers). **Parameters:** Name | Type | Description | ------ | ------ | ------ | -`a` | any | (Buffer|Array|String) | +`a` | number[] | (number[]) | -**Returns:** *any* +**Returns:** *number[]* + +(number[]) + +___ + +### `Const` unpadBuffer + +▸ **unpadBuffer**(`a`: Buffer): *Buffer* + +*Defined in [bytes.ts:67](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L67)* + +Trims leading zeros from a `Buffer`. + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`a` | Buffer | (Buffer) | + +**Returns:** *Buffer* + +(Buffer) + +___ + +### `Const` unpadHexString + +▸ **unpadHexString**(`a`: string): *string* + +*Defined in [bytes.ts:87](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L87)* + +Trims leading zeros from a hex-prefixed `String`. + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`a` | string | (String) | + +**Returns:** *string* -(Buffer|Array|String) +(String) ___ @@ -238,7 +258,7 @@ ___ ▸ **zeros**(`bytes`: number): *Buffer* -*Defined in [bytes.ts:8](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L8)* +*Defined in [bytes.ts:9](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/bytes.ts#L9)* Returns a buffer filled with 0s. diff --git a/docs/modules/_externals_.md b/docs/modules/_externals_.md index 8fb47642..2d9a6773 100644 --- a/docs/modules/_externals_.md +++ b/docs/modules/_externals_.md @@ -4,4 +4,4 @@ Re-exports commonly used modules: * Adds [`ethjs-util`](https://github.com/ethjs/ethjs-util) methods. -* Exports [`BN`](https://github.com/indutny/bn.js), [`rlp`](https://github.com/ethereumjs/rlp), [`secp256k1`](https://github.com/cryptocoinjs/secp256k1-node/). +* Exports [`BN`](https://github.com/indutny/bn.js), [`rlp`](https://github.com/ethereumjs/rlp). diff --git a/docs/modules/_hash_.md b/docs/modules/_hash_.md index 6e952759..da56fa04 100644 --- a/docs/modules/_hash_.md +++ b/docs/modules/_hash_.md @@ -8,26 +8,33 @@ * [keccak](_hash_.md#const-keccak) * [keccak256](_hash_.md#const-keccak256) +* [keccakFromArray](_hash_.md#const-keccakfromarray) +* [keccakFromHexString](_hash_.md#const-keccakfromhexstring) +* [keccakFromString](_hash_.md#const-keccakfromstring) * [ripemd160](_hash_.md#const-ripemd160) +* [ripemd160FromArray](_hash_.md#const-ripemd160fromarray) +* [ripemd160FromString](_hash_.md#const-ripemd160fromstring) * [rlphash](_hash_.md#const-rlphash) * [sha256](_hash_.md#const-sha256) +* [sha256FromArray](_hash_.md#const-sha256fromarray) +* [sha256FromString](_hash_.md#const-sha256fromstring) ## Functions ### `Const` keccak -▸ **keccak**(`a`: any, `bits`: number): *Buffer* +▸ **keccak**(`a`: Buffer, `bits`: number): *Buffer* *Defined in [hash.ts:13](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L13)* -Creates Keccak hash of the input +Creates Keccak hash of a Buffer input **Parameters:** Name | Type | Default | Description | ------ | ------ | ------ | ------ | -`a` | any | - | The input data (Buffer|Array|String|Number) If the string is a 0x-prefixed hex value it's interpreted as hexadecimal, otherwise as utf8. | -`bits` | number | 256 | The Keccak width | +`a` | Buffer | - | The input data (Buffer) | +`bits` | number | 256 | (number = 256) The Keccak width | **Returns:** *Buffer* @@ -35,9 +42,9 @@ ___ ### `Const` keccak256 -▸ **keccak256**(`a`: any): *Buffer* +▸ **keccak256**(`a`: Buffer): *Buffer* -*Defined in [hash.ts:31](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L31)* +*Defined in [hash.ts:24](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L24)* Creates Keccak-256 hash of the input, alias for keccak(a, 256). @@ -45,25 +52,120 @@ Creates Keccak-256 hash of the input, alias for keccak(a, 256). Name | Type | Description | ------ | ------ | ------ | -`a` | any | The input data (Buffer|Array|String|Number) | +`a` | Buffer | The input data (Buffer) | **Returns:** *Buffer* ___ +### `Const` keccakFromArray + +▸ **keccakFromArray**(`a`: number[], `bits`: number): *Buffer‹›* + +*Defined in [hash.ts:54](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L54)* + +Creates Keccak hash of a number array input + +**Parameters:** + +Name | Type | Default | Description | +------ | ------ | ------ | ------ | +`a` | number[] | - | The input data (number[]) | +`bits` | number | 256 | (number = 256) The Keccak width | + +**Returns:** *Buffer‹›* + +___ + +### `Const` keccakFromHexString + +▸ **keccakFromHexString**(`a`: string, `bits`: number): *Buffer‹›* + +*Defined in [hash.ts:44](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L44)* + +Creates Keccak hash of an 0x-prefixed string input + +**Parameters:** + +Name | Type | Default | Description | +------ | ------ | ------ | ------ | +`a` | string | - | The input data (String) | +`bits` | number | 256 | (number = 256) The Keccak width | + +**Returns:** *Buffer‹›* + +___ + +### `Const` keccakFromString + +▸ **keccakFromString**(`a`: string, `bits`: number): *Buffer‹›* + +*Defined in [hash.ts:33](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L33)* + +Creates Keccak hash of a utf-8 string input + +**Parameters:** + +Name | Type | Default | Description | +------ | ------ | ------ | ------ | +`a` | string | - | The input data (String) | +`bits` | number | 256 | (number = 256) The Keccak width | + +**Returns:** *Buffer‹›* + +___ + ### `Const` ripemd160 -▸ **ripemd160**(`a`: any, `padded`: boolean): *Buffer* +▸ **ripemd160**(`a`: Buffer, `padded`: boolean): *Buffer* + +*Defined in [hash.ts:102](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L102)* + +Creates RIPEMD160 hash of a Buffer input. + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`a` | Buffer | The input data (Buffer) | +`padded` | boolean | Whether it should be padded to 256 bits or not | + +**Returns:** *Buffer* + +___ -*Defined in [hash.ts:51](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L51)* +### `Const` ripemd160FromArray -Creates RIPEMD160 hash of the input. +▸ **ripemd160FromArray**(`a`: number[], `padded`: boolean): *Buffer* + +*Defined in [hash.ts:122](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L122)* + +Creates RIPEMD160 hash of a number[] input. **Parameters:** Name | Type | Description | ------ | ------ | ------ | -`a` | any | The input data (Buffer|Array|String|Number) | +`a` | number[] | The input data (number[]) | +`padded` | boolean | Whether it should be padded to 256 bits or not | + +**Returns:** *Buffer* + +___ + +### `Const` ripemd160FromString + +▸ **ripemd160FromString**(`a`: string, `padded`: boolean): *Buffer* + +*Defined in [hash.ts:112](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L112)* + +Creates RIPEMD160 hash of a string input. + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`a` | string | The input data (String) | `padded` | boolean | Whether it should be padded to 256 bits or not | **Returns:** *Buffer* @@ -74,7 +176,7 @@ ___ ▸ **rlphash**(`a`: rlp.Input): *Buffer* -*Defined in [hash.ts:67](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L67)* +*Defined in [hash.ts:148](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L148)* Creates SHA-3 hash of the RLP encoded version of the input. @@ -90,16 +192,52 @@ ___ ### `Const` sha256 -▸ **sha256**(`a`: any): *Buffer* +▸ **sha256**(`a`: Buffer): *Buffer* + +*Defined in [hash.ts:63](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L63)* + +Creates SHA256 hash of a Buffer input. + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`a` | Buffer | The input data (Buffer) | + +**Returns:** *Buffer* + +___ + +### `Const` sha256FromArray + +▸ **sha256FromArray**(`a`: number[]): *Buffer* + +*Defined in [hash.ts:81](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L81)* + +Creates SHA256 hash of a number[] input. + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`a` | number[] | The input data (number[]) | + +**Returns:** *Buffer* + +___ + +### `Const` sha256FromString + +▸ **sha256FromString**(`a`: string): *Buffer* -*Defined in [hash.ts:39](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L39)* +*Defined in [hash.ts:72](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/hash.ts#L72)* -Creates SHA256 hash of the input. +Creates SHA256 hash of a string input. **Parameters:** Name | Type | Description | ------ | ------ | ------ | -`a` | any | The input data (Buffer|Array|String|Number) | +`a` | string | The input data (string) | **Returns:** *Buffer* diff --git a/docs/modules/_helpers_.md b/docs/modules/_helpers_.md new file mode 100644 index 00000000..70afc005 --- /dev/null +++ b/docs/modules/_helpers_.md @@ -0,0 +1,84 @@ +[ethereumjs-util](../README.md) › ["helpers"](_helpers_.md) + +# Module: "helpers" + +## Index + +### Functions + +* [assertIsArray](_helpers_.md#const-assertisarray) +* [assertIsBuffer](_helpers_.md#const-assertisbuffer) +* [assertIsHexString](_helpers_.md#const-assertishexstring) +* [assertIsString](_helpers_.md#const-assertisstring) + +## Functions + +### `Const` assertIsArray + +▸ **assertIsArray**(`input`: number[]): *void* + +*Defined in [helpers.ts:29](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/helpers.ts#L29)* + +Throws if input is not an array + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`input` | number[] | value to check | + +**Returns:** *void* + +___ + +### `Const` assertIsBuffer + +▸ **assertIsBuffer**(`input`: Buffer): *void* + +*Defined in [helpers.ts:18](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/helpers.ts#L18)* + +Throws if input is not a buffer + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`input` | Buffer | value to check | + +**Returns:** *void* + +___ + +### `Const` assertIsHexString + +▸ **assertIsHexString**(`input`: string): *void* + +*Defined in [helpers.ts:7](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/helpers.ts#L7)* + +Throws if a string is not hex prefixed + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`input` | string | string to check hex prefix of | + +**Returns:** *void* + +___ + +### `Const` assertIsString + +▸ **assertIsString**(`input`: string): *void* + +*Defined in [helpers.ts:40](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/helpers.ts#L40)* + +Throws if input is not a string + +**Parameters:** + +Name | Type | Description | +------ | ------ | ------ | +`input` | string | value to check | + +**Returns:** *void* diff --git a/docs/modules/_object_.md b/docs/modules/_object_.md index 983e568c..d6b15ea3 100644 --- a/docs/modules/_object_.md +++ b/docs/modules/_object_.md @@ -12,7 +12,7 @@ ### `Const` defineProperties -▸ **defineProperties**(`self`: any, `fields`: any, `data`: any): *void* +▸ **defineProperties**(`self`: any, `fields`: any, `data?`: any): *void* *Defined in [object.ts:17](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/object.ts#L17)* @@ -24,6 +24,6 @@ Name | Type | Description | ------ | ------ | ------ | `self` | any | the `Object` to define properties on | `fields` | any | an array fields to define. Fields can contain: * `name` - the name of the properties * `length` - the number of bytes the field can have * `allowLess` - if the field can be less than the length * `allowEmpty` | -`data` | any | data to be validated against the definitions | +`data?` | any | data to be validated against the definitions | **Returns:** *void* diff --git a/docs/modules/_signature_.md b/docs/modules/_signature_.md index 96e7c35b..9c6e67d9 100644 --- a/docs/modules/_signature_.md +++ b/docs/modules/_signature_.md @@ -23,7 +23,7 @@ ▸ **ecrecover**(`msgHash`: Buffer, `v`: number, `r`: Buffer, `s`: Buffer, `chainId?`: undefined | number): *Buffer* -*Defined in [signature.ts:36](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L36)* +*Defined in [signature.ts:37](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L37)* ECDSA public key recovery from signature. @@ -47,7 +47,7 @@ ___ ▸ **ecsign**(`msgHash`: Buffer, `privateKey`: Buffer, `chainId?`: undefined | number): *[ECDSASignature](../interfaces/_signature_.ecdsasignature.md)* -*Defined in [signature.ts:15](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L15)* +*Defined in [signature.ts:16](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L16)* Returns the ECDSA signature of a message hash. @@ -67,7 +67,7 @@ ___ ▸ **fromRpcSig**(`sig`: string): *[ECDSASignature](../interfaces/_signature_.ecdsasignature.md)* -*Defined in [signature.ts:70](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L70)* +*Defined in [signature.ts:71](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L71)* Convert signature format of the `eth_sign` RPC method to signature parameters NOTE: all because of a bug in geth: https://github.com/ethereum/go-ethereum/issues/2053 @@ -86,7 +86,7 @@ ___ ▸ **hashPersonalMessage**(`message`: Buffer): *Buffer* -*Defined in [signature.ts:136](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L136)* +*Defined in [signature.ts:137](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L137)* Returns the keccak-256 hash of `message`, prefixed with the header used by the `eth_sign` RPC call. The output of this function can be fed into `ecsign` to produce the same signature as the `eth_sign` @@ -107,7 +107,7 @@ ___ ▸ **isValidSignature**(`v`: number, `r`: Buffer, `s`: Buffer, `homesteadOrLater`: boolean, `chainId?`: undefined | number): *boolean* -*Defined in [signature.ts:95](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L95)* +*Defined in [signature.ts:96](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L96)* Validate a ECDSA signature. @@ -129,7 +129,7 @@ ___ ▸ **toRpcSig**(`v`: number, `r`: Buffer, `s`: Buffer, `chainId?`: undefined | number): *string* -*Defined in [signature.ts:56](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L56)* +*Defined in [signature.ts:57](https://github.com/ethereumjs/ethereumjs-util/blob/master/src/signature.ts#L57)* Convert signature parameters into the format of `eth_sign` RPC method. diff --git a/package.json b/package.json index 349c36a7..5729af17 100644 --- a/package.json +++ b/package.json @@ -1,9 +1,12 @@ { "name": "ethereumjs-util", - "version": "6.2.0", + "version": "7.0.0", "description": "a collection of utility functions for Ethereum", "main": "dist/index.js", "types": "./dist/index.d.ts", + "engines": { + "node": ">=10.0.0" + }, "files": [ "dist" ], @@ -87,7 +90,7 @@ "homepage": "https://github.com/ethereumjs/ethereumjs-util", "dependencies": { "@types/bn.js": "^4.11.3", - "bn.js": "^4.11.0", + "bn.js": "^5.1.1", "create-hash": "^1.1.2", "ethjs-util": "0.1.6", "keccak": "^3.0.0",