91 lines
4.7 KiB
Markdown
91 lines
4.7 KiB
Markdown
|
# @ethereumjs/rlp
|
||
|
|
|
||
|
|
[![NPM Package][rlp-npm-badge]][rlp-npm-link]
|
||
|
|
[![GitHub Issues][rlp-issues-badge]][rlp-issues-link]
|
||
|
|
[![Actions Status][rlp-actions-badge]][rlp-actions-link]
|
||
|
|
[![Code Coverage][rlp-coverage-badge]][rlp-coverage-link]
|
||
|
|
[![Discord][discord-badge]][discord-link]
|
||
|
|
|
||
|
|
| [Recursive Length Prefix](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp) encoding for Node.js and the browser. |
|
||
|
|
| ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
To obtain the latest version, simply require the project using `npm`:
|
||
|
|
|
||
|
|
```shell
|
||
|
|
npm install @ethereumjs/rlp
|
||
|
|
```
|
||
|
|
|
||
|
|
Install with `-g` if you want to use the CLI.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```ts
|
||
|
|
// ./examples/simple.ts
|
||
|
|
|
||
|
|
import assert from 'assert'
|
||
|
|
import { RLP } from '@ethereumjs/rlp'
|
||
|
|
|
||
|
|
const nestedList = [[], [[]], [[], [[]]]]
|
||
|
|
const encoded = RLP.encode(nestedList)
|
||
|
|
const decoded = RLP.decode(encoded)
|
||
|
|
assert.deepStrictEqual(decoded, nestedList, 'decoded output does not match original')
|
||
|
|
console.log('assert.deepStrictEqual would have thrown if the decoded output did not match')
|
||
|
|
```
|
||
|
|
|
||
|
|
## Browser
|
||
|
|
|
||
|
|
With the breaking release round in Summer 2023 we have added hybrid ESM/CJS builds for all our libraries (see section below) and have eliminated many of the caveats which had previously prevented a frictionless browser usage.
|
||
|
|
|
||
|
|
It is now easily possible to run a browser build of one of the EthereumJS libraries within a modern browser using the provided ESM build. For a setup example see [./examples/browser.html](./examples/browser.html).
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
`RLP.encode(plain)` - RLP encodes an `Array`, `Uint8Array` or `String` and returns a `Uint8Array`.
|
||
|
|
|
||
|
|
`RLP.decode(encoded, [stream=false])` - Decodes an RLP encoded `Uint8Array`, `Array` or `String` and returns a `Uint8Array` or `NestedUint8Array`. If `stream` is enabled, it will just decode the first rlp sequence in the Uint8Array. By default, it would throw an error if there are more bytes in Uint8Array than used by the rlp sequence.
|
||
|
|
|
||
|
|
### Buffer -> Uint8Array
|
||
|
|
|
||
|
|
With the breaking releases from Summer 2023 we have removed all Node.js specific `Buffer` usages from our libraries and replace these with [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) representations, which are available both in Node.js and the browser (`Buffer` is a subclass of `Uint8Array`).
|
||
|
|
|
||
|
|
We have converted existing Buffer conversion methods to Uint8Array conversion methods in the [@ethereumjs/util](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/util) `bytes` module, see the respective README section for guidance.
|
||
|
|
|
||
|
|
### BigInt Support
|
||
|
|
|
||
|
|
Starting with v4 the usage of [BN.js](https://github.com/indutny/bn.js/) for big numbers has been removed from the library and replaced with the usage of the native JS [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) data type (introduced in `ES2020`).
|
||
|
|
|
||
|
|
Please note that number-related API signatures have changed along with this version update and the minimal build target has been updated to `ES2020`.
|
||
|
|
|
||
|
|
## CLI
|
||
|
|
|
||
|
|
`rlp encode <JSON string>`\
|
||
|
|
`rlp decode <0x-prefixed hex string>`
|
||
|
|
|
||
|
|
### Examples
|
||
|
|
|
||
|
|
- `rlp encode '5'` -> `0x05`
|
||
|
|
- `rlp encode '[5]'` -> `0xc105`
|
||
|
|
- `rlp encode '["cat", "dog"]'` -> `0xc88363617483646f67`
|
||
|
|
- `rlp decode 0xc88363617483646f67` -> `["cat","dog"]`
|
||
|
|
|
||
|
|
## EthereumJS
|
||
|
|
|
||
|
|
See our organizational [documentation](https://ethereumjs.readthedocs.io) for an introduction to `EthereumJS` as well as information on current standards and best practices. If you want to join for work or carry out improvements on the libraries, please review our [contribution guidelines](https://ethereumjs.readthedocs.io/en/latest/contributing.html) first.
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
[MPL-2.0](<https://tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)>)
|
||
|
|
|
||
|
|
[discord-badge]: https://img.shields.io/static/v1?logo=discord&label=discord&message=Join&color=blue
|
||
|
|
[discord-link]: https://discord.gg/TNwARpR
|
||
|
|
[rlp-npm-badge]: https://img.shields.io/npm/v/@ethereumjs/rlp.svg
|
||
|
|
[rlp-npm-link]: https://www.npmjs.com/package/@ethereumjs/rlp
|
||
|
|
[rlp-issues-badge]: https://img.shields.io/github/issues/ethereumjs/ethereumjs-monorepo/package:%20rlp?label=issues
|
||
|
|
[rlp-issues-link]: https://github.com/ethereumjs/ethereumjs-monorepo/issues?q=is%3Aopen+is%3Aissue+label%3A"package%3A+rlp"
|
||
|
|
[rlp-actions-badge]: https://github.com/ethereumjs/ethereumjs-monorepo/workflows/rlp/badge.svg
|
||
|
|
[rlp-actions-link]: https://github.com/ethereumjs/ethereumjs-monorepo/actions?query=workflow%3A%22rlp%22
|
||
|
|
[rlp-coverage-badge]: https://codecov.io/gh/ethereumjs/ethereumjs-monorepo/branch/master/graph/badge.svg?flag=rlp
|
||
|
|
[rlp-coverage-link]: https://codecov.io/gh/ethereumjs/ethereumjs-monorepo/tree/master/packages/rlp
|