Running a Facet Node
Introduction
To run a Facet node you will need two pieces of software: facet-node and facet-geth. This architecture follows the Consensus/Execution split on the Ethereum L1, with facet-node
acting as the consensus client and facet-geth
as the execution layer.
facet-geth is a fork of Optimism's op-geth. facet-node is modeled after op-node, though it isn't a fork.
How it works
facet-node
connects to an L1 Ethereum RPC server and monitors each L1 block for Facet transactions—i.e., transactions whose "to: address isaddress(0xface7)
or event logs whose first topic isbytes32(uint256(0xface7))
.facet-node
extracts the Facet transaction information and combines it with other data to form a transaction payload thatfacet-geth
can understand (this is called a "Deposit Transaction").facet-node
constructs a Facet block with these Deposit transactions and sends the block tofacet-geth
using the engine API. This is the same API Ethereum consensus clients use to tell the execution layer about new blocks.
facet-node
is stateless. All data required to operate facet-node
is stored in facet-geth.
Facet Genesis State
Facet's genesis block includes state from its initial pre-EVM implementation, [legacy] Facet. This state is deterministically generated by executing the latest Facet logic against historical [legacy] Facet transactions. From the perspective of running a Facet node all you need is the final genesis.json file which is included in the facet-geth
repository.
Run a Node with Docker Compose
Ensure you have Docker or Docker Desktop installed.
Clone facet-node
:
Now edit .env
. The defaults should be fine but you need to add your own L1_RPC_URL
.
Finally, start the node:
And that's it!
Run a Node without Docker
Clone
facet-node
:and
facet-geth
:Now
cd facet-node
Install Ruby Version Manager (RVM) if not already installed:
If you encounter GPG issues, run:
Install Ruby 3.3.4:
On macOS, if you encounter OpenSSL issues:
Run
rvm use 3.3.4
Run
bundle install
Set up Foundry (make sure you install it first):
Set up environment variables. First copy the .sample.env files to .env.
Now edit the files. Here's what the variables are for:
Put a JWT_SECRET in
/tmp/jwtsecret
on your local machine:Run the tests to ensure everything works.
Using facet-geth
facet-geth
To use facet-geth
to process blocks instead of just in a test:
From the
facet-node
directory, generate the geth initialization command.Copy the command, cd back into
facet-geth
, and run it. Note, this command will restart the chain from genesis, deleting any blocks you've already derived. If you want to just restart geth without doing this you should only run the /build/bin/geth command.Finally, cd back into
facet-node
and start deriving Facet blocks from L1 blocks:
You should now have facet-node
and facet-geth
set up and running!
Accessing Facet Data
You can use the geth's normal RPC API to get information about Facet blocks and transactions. For example eth_getBlockByNumber. You can also query the chain directly from the geth console which the above command launches. For example eth.getBlock(1).
From the perspective of querying data, Facet will behave identically to any other EVM chain.
Last updated