This is an NodeJS implementation of an Ultralight node that exposes a JSON-RPC for interacting with the Portal Network.
The easiest way to get started with Ultralight is to use the npm run dev script to start up a a single local node:
npm run dev along with any of the below parameters. Pass --help as a CLI parameter for a complete list of available options.
--version Show version number [boolean]
--pk base64 string encoded protobuf serialized private key
[string]
--bootnode ENR of Bootnode [string]
--bindAddress initial IP address and UDP port to bind to [string]
--bootnodeList path to a file containing a list of bootnode ENRs [string]
--rpc Enable the JSON-RPC server with HTTP endpoint
[boolean] [default: true]
--rpcPort HTTP-RPC server listening port [number] [default: 8545]
--rpcAddr HTTP-RPC server listening interface address [string]
--metrics Turn on Prometheus metrics reporting
[boolean] [default: false]
--metricsPort Port exposed for metrics scraping[number] [default: 18545]
--dataDir data directory where content is stored [string]
--web3 web3 JSON RPC HTTP endpoint for local Ethereum node for
sourcing chain data [string]
--networks subnetworks to enable
[string] [default: "history,beacon,state"]
--storage Storage space allocated to each subnetwork DB in MB
[string] [default: "1024, 1024, 1024"]
--trustedBlockRoot a trusted blockroot to start light client syncing of the
beacon chain [string]To start a node that has the same node ID each time, you can pass the --pk parameter at start-up with a hex encoded protobuf serialized private key. So tsx src/index.ts --pk=0x0a27002508021221031947fd30ff7c87d8c7ff2c0ad1515624d247970f946efda872e884a432abb634122508021221031947fd30ff7c87d8c7ff2c0ad1515624d247970f946efda872e884a432abb6341a2408021220456aad29a26c39bf438813d30bb3f0730b8b776ebc4cb0721a3d9a5b3955380e will always start the cli client with the node ID ddb83b6d279e6ab5c4d2079f6ee64b0c2c337ded9967c1226426674ef9cd4871.
The implementation teams run a few public bootnodes for interacting with other Portal Network nodes in the wild. These nodes currently support the History, Beacon, and State subnetworks.
The easiest to connect is:
DEBUG=*Portal* npm run dev-testnetYou should begin seeing logs as your local node starts to connect to the network.
Alternatively, you can specify bootnodes at start-up. Either pass in a bootnode's base64 string encoded ENR in the --bootnode CLI parameter or else pass the --bootnodeList parameter with a path to a plaintext file containing a list of base64 string encoded ENRs, one ENR per line.
The bootnodes.txt contains the ENRs for the public bootnodes designated and are intended to provide an initial connection point to the fleets of Portal Network nodes operated by implementation teams.
Run a local network of CLI Ultralight clients. Test JSON-RPC calls in a terminal, or run a test script from packages/cli/scripts/ like sampleTest.ts
- From
./packages/cli: - Run
npm run devnet -- --numNodes=3- This will start 3 nodes with JSON-RPC server addresses
[8545, 8546, 8547]
- This will start 3 nodes with JSON-RPC server addresses
- To specify a discv5 port number, include a
--portvariablenpm run devnet -- --numNodes=5 --port=9009- This will start 5 nodes with discv5 listener ports on
[9009, 9010, 9011, 9012, 9013]
- To specify which subnetworks to support, include one or more options with the
--networksparameter as shown belownpm run devnet -- --numNodes=5 --networks=history,beacon
Note, all nodes are connected to each other as bootnodes for each network by default. To turn off this behavior, pass --connectNodes=false.
currently
--pks text file containing private keys for nodes in devnet
[string]
--numNodes number of random nodes to start [number] [default: 1]
--ip ip addr [string]
--promConfig create prometheus scrape_target file
[boolean] [default: false]
--port starting port number [number] [default: 9000]
--networks supported subnetworks
[array] [default: ["history","beacon","state"]]
--connectNodes connect all nodes on network start
[boolean] [default: false]
--connectBootNodes connect to bootnodes on network start [default: false]Make JSON-RPC calls using curl or httpie
- Get a node's ENR and NodeId
http POST 127.0.0.1:8545 jsonrpc=2.0 id=1 method=discv5_nodeInfo params:=[]- __copy the
<enr>value
- __copy the
{
"id": "1",
"jsonrpc": "2.0",
"result": {
"enr": "enr:-IS4QIDbdz4hUnMDy09zUlXR5k...",
"nodeId": "0x7d878d995cab4c75608084376a93..."
}
}- Ping the first node from another
http POST 127.0.0.1:8456 jsonrpc=2.0 id=1 method=portal_historyPing params:='["<enr>"]'
{
"id": "1",
"jsonrpc": "2.0",
"result": "PING/PONG successful with 0x7d878d995cab4c75608084376a93..."
}- Add a block (header, body, receipt) to a node's database:
http POST 127.0.0.1:8545 jsonrpc=2.0 id=1 method=ultralight_addBlockToHistory params:='["<blockHash>", "<blockRlp>"]'
{
"id": "1",
"jsonrpc": "2.0",
"result": "Block <blockHash> added to content DB"
}- Retrieve block content with another
http POST 127.0.0.1:8546 jsonrpc=2.0 id=1 method=eth_getBlockByHash params:='["<blockHash>", true]'
{
id: '1',
jsonrpc: '2.0',
result: {
header: {
parentHash: '0xd32c9544473fc38...',
uncleHash: '0x1dcc4de8dec75d7a...',
coinbase: '0x52bc44d5378309ee2...',
stateRoot: '0xbf208abc4d2964e5...',
transactionsTrie: '0x25ac8c77b...',
receiptTrie: '0x435cec14c37f75...',
logsBloom: '0x0000000...',
difficulty: '0x5aae...',
number: '0x30...',
gasLimit: '0x2f...',
gasUsed: '0xf1...',
timestamp: '0x55e...',
extraData: '0xd783010102844765...',
mixHash: '0xa14a2a095183a08b07...',
nonce: '0x066ae63e55...'
},
transactions: [ [Object], [Object], [Object] ],
uncleHeaders: []
}
}
scripts/sampleTest.ts` performs the same sequence of JSON-RPC calls as above
- From
./packages/clinpm run devnet --numNodes=2starting 2 nodes...Started JSON RPC Server address=http://localhost:8545Started JSON RPC Server address=http://localhost:8546
- From
./packages/cli( in another terminal )npx tsx scripts/sampleTest.ts
See the RPC docs for details on the available RPC endpoints.
See the Networks for details on how to interact with specific subnetworks.
If it freezes during installation of dependencies when you run npm install from the monorepo root then run npm run clean from the monorepo root and try running npm install again.
If you are on fresh Macbook or similar then whilst you may have the python3 binary in your PATH, you may not also have python in your PATH, so when you run npm install from the monorepo root it may give you error env: python: No such file or directory. In that case it is necessary to create a symlink by running the following:
ln -s /Library/Developer/CommandLineTools/usr/bin/python3 /usr/local/bin/pythonRun the following from the monorepo root
npm install
npx vitest runIf you encounter an error then first run
npm run clean
Run the following from monorepo root to show linting errors and fix them to pass CI tests:
npm run lintThis requires Node version 18 or above