README
Octus Bridge relay
Runtime requirements
CPU: 8 cores, 2 GHz
RAM: 16 GB
Storage: 200 GB fast SSD
Network: 100 MBit/s
How to run
To simplify the build and create some semblance of standardization in this repository there is a set of scripts for configuring the relay.
NOTE: scripts are prepared and tested on Ubuntu 20.04. You may need to modify them a little for other distros.
Setup relay service
Native version (a little more complex way, but gives some performance gain and reduces the load):
OR docker version (the simplest way, but adds some overhead):
Not recommended for machines with lower specs than required
At this stage, a systemd service
relay
is created. Configs and keys will be in/etc/relay
and Everscale node DB will be in/var/db/relay
.Do not start this service yet!
Prepare config
Either add the environment variables to the
[Service]
section of unit file. It is located at/etc/systemd/system/relay.service
.This method is recommended because you can just make a backup of
/etc/relay
and not be afraid for it's safety, all keys in it are encryptedOr simply replace the
${..}
parameters in the config. It is located at/etc/relay/config.yaml
.Generate keys
if you already have seed phrases that you want to import, then add the
-i
flagThis script will print unencrypted data. Be sure to write it down somewhere! And also make a backup of the
/etc/relay
folder!Link relay keys
Use ETH address and Everscale public key from the previous step to link this relay setup with your staker address at https://octusbridge.io/relayers/create. When you start the linking process go to step 5 and start the relay. It will begin to confirm the public key and address on the air. It may take some time to sync at first (~40 minutes).
During linking you will need to send at least 0.05 ETH to your relay ETH address so that the relay can confirm his ownership.
If you think that this is a lot or if the gas price is more than 300 GWEI now, then you can change the values in the config.
Enable and start relay service
Relay will be running on UDP port
30000
by default, so make sure that this port is not blocked by firewall.NOTE: docker installation uses port 30000 in unit file, so you may need to update the service if you decide to change it. All environment variables must also be passed to container (e.g.
-e RELAY_MASTER_KEY
).Relay has a built-in Prometheus metrics exporter which is configured in the
metrics_settings
section of the config. By default, metrics are available athttp://127.0.0.1:10000/
Example config
NOTE: The syntax
${VAR}
can also be used everywhere in config. It will be replaced by the value of the environment variableVAR
.
Architecture overview
The relay is simultaneously the Everscale node and can communicate with all EVM networks specified in the config. Its purpose is to check and sign transaction events.
At startup, it synchronizes the Everscale node and downloads blockchain state. It searches Bridge contract state in it, all connectors, active configurations and pending events. Then it subscribes to the Bridge contract in Everscale and listens for connector deployment events. Each new connector can produce activation event which signals that relay should subscribe to the event configuration contract. Each configuration contract produces event deployment events, relay sees and checks them.
For Everscale-to-EVM events, only the correctness of data packing is checked (all other stuff is verified on the contracts side). If the event is correct, the relay converts this data into ETH ABI encoded bytes and signs it with its ETH key. This signature is sent along with a confirmation message. If the data in the event was invalid then the relay sends a rejection message.
Everscale-to-EVM ABI mapping rules:
For EVM-to-Everscale events, all event parameters are checked on the relay side. It waits for or looking for a transaction on the specified EVM network, converts event data to the TVM cell and sends a confirmation message if everything was correct. Otherwise, it sends a rejection message.
ETH-to-Everscale ABI mapping rules:
You can use https://github.com/broxus/eth-ton-abi-converter to convert data from web page
When converting ABI from EVM format to Everscale, there is a mechanism for controlling this process. You can add a
bytes1
(**) element which sets context flags to its value.Currently, there are only three flags:
0x01
- place tuples to new cell (***)0x02
- interpretbytes
as encoded TVM cell (*)0x04
- insert default cell in case of error with flag0x02
(*)
NOTE: Flags can't be changed inside an array element! This would lead to inconsistent array items ABI.
The decision to make the relay an Everscale node was not made by chance. In the first version, several relays were connected to the one "light" node which was constantly restarted or to the graphql which also was quite unreliable. As a result, relays instantly see all events and vote for them almost simultaneously in one block. The implementation is more optimized than C++ node, so they don't harm the network.
Changelog
2.3.2 (2024-03-07)
Features:
Close expired Solana events
Improve Solana metrics
Bugfixes:
Fixed clearing Solana events from pending buffer
2.3.1 (2024-02-08)
Features:
Improved shard states GC
Bugfixes:
Fixed Solana events parsing
2.3.0 (2024-01-08)
Features:
Fully reworked bridge with Solana
2.2.0 (2023-04-04)
Bugfixes:
Stability fixes
2.1.2 (2022-12-23)
Features:
Improved logger
Added support for configuration feature flags
Extend rejection info
Bugfixes:
Fixed transport issues
2.1.1 (2022-10-14)
Bugfixes:
Fixed errors with SOL events during scanning all events
Increased default polling interval
2.1.0 (2022-09-06)
Features:
Add Solana
Bugfixes:
Fixed outgoing RLDP transfers
2.0.13 (2022-07-22)
Features:
Replace
tiny-adnl
witheverscale-network
Optimize DB layout
2.0.12 (2022-06-03)
Features:
Backport transport fixes
2.0.11 (2022-04-13)
Features:
Added archives assembly
Added new account model support
Bugfixes
Fixed ADNL channels
2.0.10 (2022-04-03)
Bugfixes
Fixed memory leaks. (New peers queue was read at a fixed rate).
2.0.9 (2022-03-26)
Features
Added packets compression support (enabled by default).
Various optimizations.
2.0.8 (2022-02-12)
Features
Updated ABI version to 2.2
Fixed memory leaks. (Shard states were slowly filling with loaded storage cells).
2.0.7 (2022-02-02)
Features
ADNL security improvements
2.0.6 (2021-12-31)
Features
Optimized DB structure
2.0.5 (2021-11-27)
Features
Improved ETH events verification
Updated events ABI
Added
ton_subscriber_shard_client_time_diff
,ton_subscriber_mc_block_seqno
andton_subscriber_shard_client_mc_block_seqno
values into metrics
2.0.4 (2021-11-11)
Features
Use jemalloc by default
Bugfixes
Fixed blocks GC memory issues
2.0.3 (2021-11-09)
Features
Hot reload for metrics exporter and logger settings (SIGHUP signal)
Blocks and states garbage collection
Additional EVM RPC timing controls
Improved database layout and increased data locality
Bugfixes
Fixed exported metrics format
Fixed event confirmation counters
Fixed time diff metrics
Reduced blocks range for
eth_getLogs
Ignore descending blocks for ETH rpc
2.0.2
Features
Added setup scripts for fast deployment
Bugfixes
Fixed bridge contracts interaction logic according to new changes
2.0.1
Initial release
Last updated