Skip to content

Commit c126547

Browse files
m4sterbunnyjulien-marchand
m4sterbunny
and
julien-marchand
authored
docs:extends userdocs (#57)
* docs:extends userdocs * docs:extends userdocs * Update README.md repo name change & update of descriptions * Update README.md updated description * Update README.md updated description * Update README.md adds verbose description * Update README.md moving this repo to top * Update README.md moves this repo to top * Update README.md --------- Co-authored-by: Julien Marchand <[email protected]>
1 parent b58d652 commit c126547

File tree

5 files changed

+158
-84
lines changed

5 files changed

+158
-84
lines changed

‎LICENSE

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# License
2+
3+
Copyright 2024 Consensys Software Inc.
4+
5+
Licensed under the Apache License, Version 2.0 (the "License");
6+
you may not use this file except in compliance with the License.
7+
You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.

‎README.md

+40-75
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,63 @@
11
# Besu Plugins related to tracer and sequencer functionality
22

3-
A set of Linea plugins for the sequencer and RPC nodes.
3+
This repository hosts the implementation of the sequencer, the component of the Linea stack responsible for ordering transactions and building blocks, as well as executing them. It provides a set of [Hyperledger Besu](https://github.com/hyperledger/besu):Linea plugins.
44

5-
## Quickstart - Running [Linea Besu](https://github.com/Consensys/linea-besu) with plugins
5+
It serves developers by making the Linea tech stack open source under
6+
the [Apache 2.0 license](LICENSE).
67

7-
- compile linea-plugins `gradlew installDist`
8-
- copy jar file to besu runtime plugins/ directory (where you will run besu from, not where you're building besu)
9-
- add `LINEA` to besu config to enable the plugin RPC methods
10-
- rpc-http-api=\["ADMIN","ETH","NET","WEB3","LINEA"\]
11-
- start besu (command line or from IDE) and you should see plugins registered at startup
12-
- call the RPC endpoint eg:
8+
## What is Linea?
139

14-
```shell
15-
curl --location --request POST 'http://localhost:8545' --data-raw '{
16-
"jsonrpc": "2.0",
17-
"method": "linea_estimateGas",
18-
"params": [
19-
"from": "0x73b2e0E54510239E22cC936F0b4a6dE1acf0AbdE",
20-
"to": "0xBb977B2EE8a111D788B3477D242078d0B837E72b",
21-
"value": "0x123"
22-
],
23-
"id": 1
24-
}'
25-
```
10+
[Linea](https://linea.build) is a developer-ready layer 2 network scaling Ethereum. It's secured with a zero-knowledge rollup, built on lattice-based cryptography, and powered by [Consensys](https://consensys.io).
2611

27-
## Development Setup
12+
## Get started
2813

29-
### Install Java 21
14+
If you already have an understanding of the tech stack, use our [Quickstart](docs/quickstart.md) guide.
3015

31-
### Native Lib Prerequisites
16+
### Looking for Plugins?
3217

33-
Linux/MacOs
34-
* Install the relevant CGo compiler for your platform
35-
* Install the Go toolchain
18+
Discover [existing plugins](docs/plugins.md) and understand the [plugin release process](docs/plugin-release.md).
3619

37-
Windows
38-
* Requirement [Docker Desktop WSL 2 backend on Windows](https://docs.docker.com/desktop/wsl/)
20+
## Looking for the Linea code?
3921

40-
On release native libs are built for all the supported platforms,
41-
if you want to test this process locally run `./gradlew -PreleaseNativeLibs jar`,
42-
jar is generated in `sequencer/build/libs`.
22+
Linea's stack is made up of multiple repositories, these include:
23+
- This repo, [linea-sequencer](https://github.com/Consensys/linea-sequencer): A set of Linea-Besu plugins for the sequencer and RPC nodes
24+
- [linea-monorepo](https://github.com/Consensys/linea-monorepo): The main repository for the Linea stack & network
25+
- [linea-besu](https://github.com/Consensys/linea-besu): Fork of Besu to implement the Linea-Besu client
26+
- [linea-tracer](https://github.com/Consensys/linea-tracer): Linea-Besu plugin which produces the traces that the constraint system applies and that serve as inputs to the prover
27+
- [linea-constraints](https://github.com/Consensys/linea-constraints): Implementation of the constraint system from the specification
28+
- [linea-specification](https://github.com/Consensys/linea-specification): Specification of the constraint system defining Linea's zk-EVM
4329

44-
### Run tests
30+
Linea abstracts away the complexity of this technical architecture to allow developers to:
4531

46-
```shell
47-
# Run all tests
48-
./gradlew clean test
32+
- [Bridge tokens](https://docs.linea.build/developers/guides/bridge)
33+
- [Deploy a contract](https://docs.linea.build/developers/quickstart/deploy-smart-contract)
34+
- [Run a node](https://docs.linea.build/developers/guides/run-a-node)
4935

50-
# Run only acceptance tests
51-
./gradlew clean acceptanceTests
52-
```
36+
... and more.
5337

54-
## IntelliJ IDEA Setup
38+
## How to contribute
5539

56-
### Enable Annotation Processing
40+
Contributions of any kind are welcome!
5741

58-
- Go to `Settings | Build, Execution, Deployment | Compiler | Annotation Processors` and tick the following
59-
checkbox:
42+
1. [Create an issue](https://github.com/Consensys/linea-sequencer/issues).
43+
> If the proposed update is non-trivial, also tag us for discussion.
44+
2. Submit the update as a pull request from your [fork of this repo](https://github.com/Consensys/linea-sequencer/fork), and tag us for review.
45+
> Include the issue number in the pull request description and (optionally) in the branch name.
6046
61-
![idea_enable_annotation_processing_setting.png](images/idea_enable_annotation_processing_setting.png)
47+
Consider starting with a ["good first issue"](https://github.com/ConsenSys/linea-sequencer/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
6248

63-
______________________________________________________________________
49+
Before contributing, ensure you're familiar with:
6450

65-
NOTE
51+
- Our [Linea contribution guide](https://github.com/Consensys/linea-monorepo/blob/main/docs/contribute.md)
52+
- Our [Linea code of conduct](https://github.com/Consensys/linea-monorepo/blob/main/docs/code-of-conduct.md)
53+
- The [Besu contribution guide](https://github.com/Consensys/linea-monorepo/blob/main/https://wiki.hyperledger.org/display/BESU/Coding+Conventions), for Besu:Linea related contributions
54+
- Our [Security policy](https://github.com/Consensys/linea-monorepo/blob/main/docs/security.md)
6655

67-
> This setting is required to avoid IDE compilation errors because of the [Lombok](https://projectlombok.org/features/)
68-
> library used for code generation of boilerplate Java code such as:
69-
>
70-
> - Getters/Setters (via [`@Getter/@Setter`](https://projectlombok.org/features/GetterSetter))
71-
> - Class log instances (via [`@Slf4j`](https://projectlombok.org/features/log))
72-
> - Builder classes (via [`@Builder`](https://projectlombok.org/features/Builder))
73-
> - Constructors (
74-
> via [`@NoArgsConstructor/@RequiredArgsConstructor/@AllArgsConstructor`](https://projectlombok.org/features/constructor))
75-
> - etc.
76-
>
77-
> Learn more about how Java annotation processing
78-
> works [here](https://www.baeldung.com/java-annotation-processing-builder).
7956

80-
______________________________________________________________________
57+
### Useful links
8158

82-
### Install Optional Plugins
83-
84-
- Install [Spotless Gradle](https://plugins.jetbrains.com/plugin/18321-spotless-gradle) plugin to re-format through
85-
the IDE according to spotless configuration.
86-
87-
## Plugins
88-
89-
Plugins are documented [here](PLUGINS.md).
90-
91-
## Release Process
92-
Here are the steps for releasing a new version of the plugins:
93-
1. Create a tag with the release version number in the format vX.Y.Z (e.g., v0.2.0 creates a release version 0.2.0).
94-
2. Push the tag to the repository.
95-
3. GitHub Actions will automatically create a draft release for the release tag.
96-
4. Once the release workflow completes, update the release notes, uncheck "Draft", and publish the release.
97-
98-
Note: Release tags (of the form v*) are protected and can only be pushed by organization and/or repository owners.
59+
- [Linea docs](https://docs.linea.build)
60+
- [Linea blog](https://linea.mirror.xyz)
61+
- [Support](https://support.linea.build)
62+
- [Discord](https://discord.gg/linea)
63+
- [Twitter](https://twitter.com/LineaBuild)

‎docs/plugin-release.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Plugin release process
2+
3+
Here are the steps for releasing a new version of the plugins:
4+
1. Create a tag with the release version number in the format vX.Y.Z (e.g., v0.2.0 creates a release version 0.2.0).
5+
2. Push the tag to the repository.
6+
3. GitHub Actions will automatically create a draft release for the release tag.
7+
4. Once the release workflow completes, update the release notes, uncheck "Draft", and publish the release.
8+
9+
Note: Release tags (of the form v*) are protected and can only be pushed by organization and/or repository owners.

‎PLUGINS.md ‎docs/plugins.md

+11-9
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
# Linea plugins
22

33
## Shared components
4+
45
### Profitability calculator
56
The profitability calculator is a shared component, that is used to check if a tx is profitable.
6-
It is applied, with different configuration to:
7+
It's applied, with different configuration to:
78
1. `linea_estimateGas` endpoint
89
2. Tx validation for the txpool (if tx profitability check is enabled)
910
3. Tx selection during block creation
1011

11-
#### CLI Options
12+
#### CLI options
1213

1314
| Command Line Argument | Default Value |
1415
|-------------------------------------------------------|---------------|
@@ -28,15 +29,16 @@ It is used in:
2829
2. Tx validation for the txpool (if tx simulation is enabled)
2930
3. Tx selection during block creation
3031

31-
#### CLI Options
32+
#### CLI options
3233

3334
| Command Line Argument | Default Value |
3435
|-------------------------------------------------------|----------------------|
3536
| `--plugin-linea-module-limit-file-path` | moduleLimitFile.toml |
3637
| `--plugin-linea-over-line-count-limit-cache-size` | 10_000 |
3738

3839

39-
### L1 L2 Bridge
40+
### L1<>L2 bridge
41+
4042
These values are just passed to the ZkTracer
4143

4244
#### CLI Options
@@ -49,14 +51,14 @@ These values are just passed to the ZkTracer
4951

5052
## Sequencer
5153

52-
### Transaction Selection - LineaTransactionSelectorPlugin
54+
### Transaction selection - LineaTransactionSelectorPlugin
5355
This plugin extends the standard transaction selection protocols employed by Besu for block creation.
5456
It leverages the `TransactionSelectionService` to manage and customize the process of transaction selection.
5557
This includes setting limits such as `TraceLineLimit`, `maxBlockGas`, and `maxCallData`, and check the profitability
5658
of a transaction.
5759
The selectors are in the package `net.consensys.linea.sequencer.txselection.selectors`.
5860

59-
#### CLI Options
61+
#### CLI options
6062

6163
| Command Line Argument | Default Value |
6264
|--------------------------------------------------------|----------------------|
@@ -68,7 +70,7 @@ The selectors are in the package `net.consensys.linea.sequencer.txselection.sele
6870
| `--plugin-linea-unprofitable-retry-limit` | 10 |
6971

7072

71-
### Transaction Validation - LineaTransactionValidatorPlugin
73+
### Transaction validation - LineaTransactionValidatorPlugin
7274

7375
This plugin extends the default transaction validation rules for adding transactions to the
7476
transaction pool. It leverages the `PluginTransactionValidatorService` to manage and customize the
@@ -77,7 +79,7 @@ This includes setting limits such as `TraceLineLimit`, `maxTxGasLimit`, and `max
7779
of a transaction.
7880
The validators are in the package `net.consensys.linea.sequencer.txpoolvalidation.validators`.
7981

80-
#### CLI Options
82+
#### CLI options
8183

8284
| Command Line Argument | Default Value |
8385
|----------------------------------------------------------|-------------------|
@@ -90,7 +92,7 @@ The validators are in the package `net.consensys.linea.sequencer.txpoolvalidatio
9092
| `--plugin-linea-tx-pool-profitability-check-p2p-enabled` | false |
9193

9294

93-
## RPC Methods
95+
## RPC methods
9496

9597
### Linea Estimate Gas
9698
#### `linea_estimateGas`

‎docs/quickstart.md

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
## Quickstart: running [Linea Besu](https://github.com/Consensys/linea-besu) with plugins
2+
3+
- compile linea-plugins `gradlew installDist`
4+
- copy jar file to besu runtime plugins/ directory (where you will run Besu from, not where you're building Besu)
5+
- add `LINEA` to besu config to enable the plugin RPC methods
6+
- rpc-http-api=\["ADMIN","ETH","NET","WEB3","LINEA"\]
7+
- start besu (command line or from IDE) and you should see plugins registered at startup
8+
- call the RPC endpoint eg:
9+
10+
```shell
11+
curl --location --request POST 'http://localhost:8545' --data-raw '{
12+
"jsonrpc": "2.0",
13+
"method": "linea_estimateGas",
14+
"params": [
15+
"from": "0x73b2e0E54510239E22cC936F0b4a6dE1acf0AbdE",
16+
"to": "0xBb977B2EE8a111D788B3477D242078d0B837E72b",
17+
"value": "0x123"
18+
],
19+
"id": 1
20+
}'
21+
```
22+
23+
## Development Setup
24+
25+
### Install Java 21
26+
27+
### Native Lib Prerequisites
28+
29+
Linux/MacOs
30+
* Install the relevant CGo compiler for your platform
31+
* Install the Go toolchain
32+
33+
Windows
34+
* Requirement [Docker Desktop WSL 2 backend on Windows](https://docs.docker.com/desktop/wsl/)
35+
36+
On release native libs are built for all the supported platforms,
37+
if you want to test this process locally run `./gradlew -PreleaseNativeLibs jar`,
38+
jar is generated in `sequencer/build/libs`.
39+
40+
### Run tests
41+
42+
```shell
43+
# Run all tests
44+
./gradlew clean test
45+
46+
# Run only acceptance tests
47+
./gradlew clean acceptanceTests
48+
```
49+
50+
## IntelliJ IDEA Setup
51+
52+
### Enable Annotation Processing
53+
54+
- Go to `Settings | Build, Execution, Deployment | Compiler | Annotation Processors` and tick the following
55+
checkbox:
56+
57+
![idea_enable_annotation_processing_setting.png](images/idea_enable_annotation_processing_setting.png)
58+
59+
______________________________________________________________________
60+
61+
NOTE
62+
63+
> This setting is required to avoid IDE compilation errors because of the [Lombok](https://projectlombok.org/features/)
64+
> library used for code generation of boilerplate Java code such as:
65+
>
66+
> - Getters/Setters (via [`@Getter/@Setter`](https://projectlombok.org/features/GetterSetter))
67+
> - Class log instances (via [`@Slf4j`](https://projectlombok.org/features/log))
68+
> - Builder classes (via [`@Builder`](https://projectlombok.org/features/Builder))
69+
> - Constructors (
70+
> via [`@NoArgsConstructor/@RequiredArgsConstructor/@AllArgsConstructor`](https://projectlombok.org/features/constructor))
71+
> - etc.
72+
>
73+
> Learn more about how Java annotation processing
74+
> works [here](https://www.baeldung.com/java-annotation-processing-builder).
75+
76+
______________________________________________________________________
77+
78+
### Install Optional Plugins
79+
80+
- Install [Spotless Gradle](https://plugins.jetbrains.com/plugin/18321-spotless-gradle) plugin to re-format through
81+
the IDE according to spotless configuration.
82+
83+
Learn more [about available plugins](plugins.md).

0 commit comments

Comments
 (0)