You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tuweni.apache.org by to...@apache.org on 2023/01/30 04:13:54 UTC
[incubator-tuweni] branch main updated: more READMEs
This is an automated email from the ASF dual-hosted git repository.
toulmean pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-tuweni.git
The following commit(s) were added to refs/heads/main by this push:
new 839c31a7f more READMEs
new 636ffb07e Merge pull request #504 from atoulme/add_readmes
839c31a7f is described below
commit 839c31a7f44d991747319ba775cbbf447d8e5399
Author: Antoine Toulme <an...@lunar-ocean.com>
AuthorDate: Sun Jan 29 18:43:56 2023 -0800
more READMEs
---
eth-client/README.md | 61 +++++++++++++++++++++++++++
eth-crawler/README.md | 17 ++++++++
eth-faucet/README.md | 85 +++++++++++++++++++++++++++++++-------
gossip/README.md | 60 +++++++++++++++++++++++++++
hobbits-relayer/README.md | 38 +++++++++++++++++
jsonrpc-app/README.md | 43 +++++++++++++++++++
net/README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++
7 files changed, 392 insertions(+), 14 deletions(-)
diff --git a/eth-client/README.md b/eth-client/README.md
new file mode 100644
index 000000000..1bea31757
--- /dev/null
+++ b/eth-client/README.md
@@ -0,0 +1,61 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE
+file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+License. You may obtain a copy of the License at
+ *
+http://www.apache.org/licenses/LICENSE-2.0
+ *
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+ --->
+# Ethereum client
+
+The `tuweni` application is an Ethereum client that can run multiple chains and multiple discovery mechanisms.
+
+`tuweni` can sync multiple chains at once. It also has a web UI.
+
+NOTE: everything at this point is at best a prototype. This may change at any time.
+
+Usage:
+
+```bash
+Apache Tuweni client loading
+Usage: <main class> [-h] [-c=<configPath>] [-w=<web>]
+-c, --config=<configPath>
+Configuration file.
+-h, --help Prints usage prompt
+-w, --web=<web> Web console host:port
+```
+
+Most of the action happens in the configuration file, written with TOML.
+
+Example with one chain:
+
+```toml
+[storage.default]
+path="data"
+genesis="default"
+[genesis.default]
+path=default.json
+```
+
+The `default.json` file is your usual genesis configuration file.
+
+Example with two chains:
+
+Example with one chain:
+
+```toml
+[storage.foo]
+path="data"
+genesis="foo"
+[genesis.foo]
+path=default.json
+[storage.bar]
+path="data"
+genesis="bar"
+[genesis.bar]
+path=other.json
+```
\ No newline at end of file
diff --git a/eth-crawler/README.md b/eth-crawler/README.md
new file mode 100644
index 000000000..16ebab3e4
--- /dev/null
+++ b/eth-crawler/README.md
@@ -0,0 +1,17 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE
+file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+License. You may obtain a copy of the License at
+ *
+http://www.apache.org/licenses/LICENSE-2.0
+ *
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+ --->
+# Ethereum crawler
+
+The crawler is a discv5 server that constantly looks for new peers.
+
+Whenever it connects to peers, it asks for all their known peers, and keeps going until it has exhausted all peers it could discover, then starts all over again.
diff --git a/eth-faucet/README.md b/eth-faucet/README.md
index 66ad8abcf..6752705a8 100644
--- a/eth-faucet/README.md
+++ b/eth-faucet/README.md
@@ -1,10 +1,80 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE
+file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+License. You may obtain a copy of the License at
+ *
+http://www.apache.org/licenses/LICENSE-2.0
+ *
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+ --->
# Ethereum Faucet
This example allows you to set up a faucet with Github authentication.
The application is written in Kotlin with Spring Boot, with Spring Web, Spring Security and Thymeleaf templates.
-The app is configured with the values in src/main/resources/application.yml.
+## Configuration
+
+The faucet works with a configuration file, `application.yml`. Here is a template of the file:
+
+```yaml
+server:
+ use-forward-headers: true
+ forward-headers-strategy: native
+spring:
+ main:
+ banner-mode: "off"
+ security:
+ oauth2:
+ client:
+ registration:
+ github:
+ clientId: <your github client ID>
+ clientSecret: <your github client secret>
+html:
+ title: Faucet
+ request_message: Welcome to our faucet. You can ask for up to 1 ETH on this faucet.
+
+security:
+ oauth2:
+ client:
+ preEstablishedRedirectUri: <registered github redirect URI>
+ registeredRedirectUri: <registered github redirect URI>
+ useCurrentUri: false
+
+faucet:
+ maxETH: <the maximum amount of eth, in ETH, that you>
+ chainId: <chain id of your network>
+ rpcPort: <Ethereum client RPC port>
+ rpcHost: <Ethereum client RPC host>
+
+wallet:
+ path: wallet.key
+banner: >
+ Apache Tuweni Faucet example.
+
+
+ `:oyhdhhhhhhyo-`
+ :yds/. ./sdy:
+ :mh: :hm:
+ `ym: :my`
+ hm` `mh
+ +N. .N+
+ my :ydh/ /hdy- ym
+ Mo`MMMMM` .MMMMN oM
+ my /hdh/ +hdh: ym
+ +N. .N+
+ hm` `m: `mh
+ `ym: `sssssssssN: :my`
+ :dh: `````````` :hd:
+ :yds/. ./sdy:
+ `-oyhdhhhhdhyo-`
+```
+
+You should register a Github OAuth application to go along and fill the template.
# Faucet
@@ -39,16 +109,3 @@ In the web page, note the faucet account address. Make sure to send money to tha
Now you can send money using the faucet. Enter any valid address and press OK.
The second time you ask for money, the faucet will detect the balance of the account matches the max the faucet with top up.
-
-# License
-
-Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE
-file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
-to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
-License. You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
-an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
-specific language governing permissions and limitations under the License.
diff --git a/gossip/README.md b/gossip/README.md
new file mode 100644
index 000000000..c653d63a0
--- /dev/null
+++ b/gossip/README.md
@@ -0,0 +1,60 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE
+file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+License. You may obtain a copy of the License at
+ *
+http://www.apache.org/licenses/LICENSE-2.0
+ *
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+ --->
+# Gossip
+
+The `gossip` application is an example showing how the Plumtree gossip implementation functions.
+
+`gossip` is distributed as part of the binary distribution of Apache Tuweni, which you can download from this [page](/download)
+
+```bash
+./gossip --help
+Usage: <main class> [-h] [--sending] [--numberOfMessages=<numberOfMessages>]
+ [--payloadSize=<payloadSize>]
+ [--sendInterval=<sendInterval>] [-c=<configPath>]
+ [-l=<port>] [-m=<messageLog>] [-n=<networkInterface>]
+ [-r=<rpcPort>] [-p[=<peers>...]]...
+ --numberOfMessages=<numberOfMessages>
+ Number of messages to publish (load testing)
+ --payloadSize=<payloadSize>
+ Size of the random payload to send to other peers (load
+ testing)
+ --sending Whether this peer sends random messages to all other
+ peers (load testing)
+ --sendInterval=<sendInterval>
+ Interval to wait in between sending messages in
+ milliseconds (load testing)
+ -c, --config=<configPath> Configuration file.
+ -h, --help Prints usage prompt
+ -l, --listen=<port> Port to listen on
+ -m, --messageLog=<messageLog>
+ Log file where messages are stored
+ -n, --networkInterface=<networkInterface>
+ Network interface to bind to
+ -p, --peer[=<peers>...] Static peers list
+ -r, --rpc=<rpcPort> RPC port to listen on
+```
+
+You can set up a `gossip` app to listen with this command:
+```bash
+./gossip -l 9000 -m /tmp/log
+```
+
+In a separate shell, you can send messages to the listener with:
+
+```bash
+./gossip -l 9001 -p 127.0.0.1:9000 --sending --payloadSize=32 --numberOfMessages=10 -p tcp://127.0.0.1:9000 --sendInterval=1000
+```
+
+This will send 10 messages, of 32 random bytes each. Open the file `/tmp/log` to see them.
+
+You can create more complex scenarios with multiple gossip listeners, showing the path by which gossip circulates across peers.
\ No newline at end of file
diff --git a/hobbits-relayer/README.md b/hobbits-relayer/README.md
new file mode 100644
index 000000000..fd33c2d56
--- /dev/null
+++ b/hobbits-relayer/README.md
@@ -0,0 +1,38 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE
+file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+License. You may obtain a copy of the License at
+ *
+http://www.apache.org/licenses/LICENSE-2.0
+ *
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+ --->
+The `hobbits-relayer` application showcases how to use the Hobbits protocol to pass messages between different networks.
+
+```bash
+hobbits-relayer --help
+Usage: <main class> [-h] [-b=<bind>] [-t=<to>]
+-b, --bind=<bind> Endpoint to bind to
+-h, --help Prints usage prompt
+-t, --to=<to> Endpoint to relay to
+```
+
+Example use:
+
+Relay messages over TCP from port 21000 to 22000:
+```bash
+hobbits-relayer -b tcp://localhost:21000 -t tcp://localhost:22000
+```
+
+Relay messages over UDP from port 2222 to 4444:
+```bash
+hobbits-relayer -b udp://localhost:2222 -t udp://localhost:4444
+```
+
+Relay messages from a Web Socket port 2222 to a TCP server on 4444:
+```bash
+hobbits-relayer -b ws://localhost:2222 -t tcp://localhost:4444
+```
\ No newline at end of file
diff --git a/jsonrpc-app/README.md b/jsonrpc-app/README.md
new file mode 100644
index 000000000..5036a0aa6
--- /dev/null
+++ b/jsonrpc-app/README.md
@@ -0,0 +1,43 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE
+file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+License. You may obtain a copy of the License at
+ *
+http://www.apache.org/licenses/LICENSE-2.0
+ *
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+ --->
+# JSONRPC
+
+The `jsonrpc` application is a JSON-RPC proxy that can cache, filter, throttle, meter and authenticate requests to a JSON-RPC endpoint.
+
+The application is configured via a toml file, described below:
+
+## Examples
+
+### Proxy a JSON-RPC endpoint publicly
+
+You set up a node and want to proxy. You expose all JSON-RPC methods on your node but only want to expose the `eth_` namespace publicly, with HTTP Basic authentication:
+
+```toml
+endpointUrl="http://192.168.1.2:8545" # IP of your node
+allowedMethods=["eth_"]
+cacheEnabled=true
+cachedMethods=["eth_"]
+cacheStoragePath="/var/jsonrpccache" # Cache location
+```
+
+### Local development
+
+You have a local development and you're using a RPC provider, but you want to work without calling the service constantly.
+
+```toml
+endpointUrl="https://example.com:8545/?token=mytoken" # service URL
+cacheEnabled=true
+cachedMethods=[""] # All methods are cached
+cacheStoragePath="/var/jsonrpccache" # Cache location
+allowedMethods=[""] # All methods are enabled
+```
\ No newline at end of file
diff --git a/net/README.md b/net/README.md
new file mode 100644
index 000000000..209d19215
--- /dev/null
+++ b/net/README.md
@@ -0,0 +1,102 @@
+<!---
+Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE
+file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file
+to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+License. You may obtain a copy of the License at
+ *
+http://www.apache.org/licenses/LICENSE-2.0
+ *
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+ --->
+# Net
+
+# Getting started
+
+To get started, install the `net` library.
+
+With Maven:
+
+```xml
+<dependency>
+<groupId>org.apache.tuweni</groupId>
+<artifactId>net</artifactId>
+<version>{{site.data.project.latest_release}}</version>
+</dependency>
+```
+
+Or using Gradle:
+
+```groovy
+implementation("org.apache.tuweni:net:{{site.data.project.latest_release}}")
+```
+
+If you haven't already, you will also need to add Bouncy Castle to your dependencies, and add the Bouncy Castle Security Provider to Java.
+
+```java
+Security.addProvider(new BouncyCastleProvider());
+```
+
+# Permissions
+
+Since we're engaging in peer-to-peer applications, we will define different scenarios for trust.
+
+First off, we will engage in two-way certificate authentication. The server will provide its certificate to the client and the client will also need to provide its identity.
+
+All those settings are taken after the [Constellation private enclave network options](https://github.com/consensys/constellation).
+
+## CA
+By default, Java uses Certificate Authorities on the machine to authenticate a trusted certificate.
+
+## Recording
+We can also choose to record the fingerprints of incoming connections while authorizing all of them.
+
+## Trust On First Use (TOFU)
+In this setting, incoming connections are recorded, and their certificates are collected, but only the first certificate assigned to a connection is allowed.
+
+This is a good way to mitigate MITM attacks.
+
+## Allowlist
+
+Only explicit hosts and certificate combinations are allowed.
+
+# TrustManagerFactories
+
+[`TrustManagerFactory` implementations](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/javax/net/ssl/TrustManagerFactory.html) provide trust with JDK and most Java-based servers.
+
+The [`TrustManagerFactories` API](/docs/org.apache.tuweni.net.tls/-trust-manager-factories/index.html) creates `TrustManagerFactory` objects for client and server communications.
+
+As an example, the following method creates a `TrustManagerFactory` that records incoming connections into a `knownServersFile`, but only the ones that don't have a signed CA certificate.
+
+```java
+TrustManagerFactories.recordServerFingerprints(knownServersFile, false);
+```
+
+# VertxTrustOptions
+
+The [`VertxTrustOptions` API](/docs/org.apache.tuweni.net.tls/-vertx-trust-options/index.html) is a quick drop-in API to configure Vert.x servers and clients for communications.
+
+In the example below, we set a server to require client authentication and trust clients on first access (TOFU).
+```java
+HttpServerOptions options = new HttpServerOptions();
+options.setSsl(true)
+.setClientAuth(ClientAuth.REQUIRED)
+.setPemKeyCertOptions(serverCert.keyCertOptions())
+.setTrustOptions(VertxTrustOptions.trustClientOnFirstAccess(knownClientsFile))
+.setIdleTimeout(1500)
+.setReuseAddress(true)
+.setReusePort(true);
+httpServer = vertx.createHttpServer(options);
+```
+
+In this example, we set a HTTP client to communicate with servers that are whitelisted only (and not even trust CA-signed certificates):
+```java
+HttpClientOptions options = new HttpClientOptions();
+options.setSsl(true)
+.setTrustOptions(VertxTrustOptions.whitelistServers(knownServersFile, false))
+.setConnectTimeout(1500)
+.setReuseAddress(true)
+.setReusePort(true);
+client = vertx.createHttpClient(options);
+```
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@tuweni.apache.org
For additional commands, e-mail: commits-help@tuweni.apache.org