Skip to content

Update documentation to use attested-tls-proxy rather than cvm-reverse-proxy for getting TLS certificates #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ameba23 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update documentation to use attested-tls-proxy rather than cvm-reverse-proxy for getting TLS certificates #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c8577f7
Update documentation to use attested-tls-proxy rather than cvm-revers…
ameba23 Feb 26, 2026
4f34aa3
Update expected output to match what we actually see
ameba23 Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 9 additions & 11 deletions docs/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -206,18 +206,17 @@ You can find more details in the [Constellation docs](https://docs.edgeless.syst
>
> The protocol can be used by clients to verify a server certificate, by a server to verify a client certificate, or for mutual verification (mutual aTLS).

In BuilderNet, [github.com/flashbots/cvm-reverse-proxy](https://github.com/flashbots/cvm-reverse-proxy) is responsible for attested TLS (aTLS) communication, both towards users as well as within the network.
You can use the [`attested-get`](https://github.com/flashbots/cvm-reverse-proxy/blob/main/cmd/attested-get/main.go) tool to receive the builder certificate over an attested channel:
In BuilderNet,
[github.com/flashbots/attested-tls-proxy](https://github.com/flashbots/attested-tls-proxy) is responsible for attested TLS communication, both towards users as well as within the network.
You can use the [`attested-tls-proxy get-tls-cert`](https://github.com/flashbots/attested-tls-proxy) command to receive the builder certificate over an attested channel:

```bash
# Install attested-get
go install github.com/flashbots/cvm-reverse-proxy/cmd/attested-get

# Get the builder certificate over an attested channel
attested-get \
--addr=https://rpc.buildernet.org:7936/cert \
--expected-measurements=https://measurements.buildernet.org \
--out-response=builder-cert.pem
cargo install --git https://github.com/flashbots/attested-tls-proxy attested-tls-proxy
# optionally add --tag <version number of latest release>
Copy link
Copy Markdown
Author

@ameba23 ameba23 Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately there isn't a way to tell cargo to use the latest published release when installing from git rather than crates.io. This would be an argument to publish this to crates.io - but then we have the issue that crate versions do not [currently] necessarily match release tag versions.


attested-tls-proxy get-tls-cert \
--measurements-file https://measurements.buildernet.org \
rpc.buildernet.org:7936/cert > builder-cert.pem
```

See also "[Orderflow encryption and attestation](encryption-attestations)" for more details.
Expand Down Expand Up @@ -471,4 +470,3 @@ The response contains three fields:
- `pending`: the total amount of fee refunds that have been earned but not yet received by the recipient
- `received`: the total amount of fee refunds that have been received by the recipient


33 changes: 19 additions & 14 deletions docs/encryption-attestations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,37 +39,42 @@ Client requests require the server to own the private key for this particular TL
## TEE attestation of the certificate

TEE attestation allows you to verify that a given TLS certificate belongs to a particular VM image (with specific codebase and configuration).
On every builder node, an API on port 7936 serves the local certificate over an aTLS attested channel.
On every builder node, an API on port 7936 serves the local certificate over an attested-TLS channel.

:::info

Read more about aTLS in the [Constellation documentation](https://github.com/edgelesssys/constellation/blob/main/internal/atls/README.md).
Read more about attested-tls in the [documentation](https://github.com/flashbots/attested-tls-proxy/tree/main/attested-tls/README.md).

:::


As part of the aTLS handshake, the client (i.e. user) can verify that the server runs inside a TEE instance with specific measurements
As part of the attested-TLS handshake, the client (i.e. user) can verify that the server runs inside a TEE instance with specific measurements
(i.e. specific codebase and configuration).

You can use [this tool](https://github.com/flashbots/cvm-reverse-proxy/blob/main/cmd/attested-get/main.go) to get the certificate with TEE attestation:
You can use [this tool](https://github.com/flashbots/attested-tls-proxy) to get the certificate with TEE attestation:

Installing with `cargo`:

```bash
# Install attested-get
go install github.com/flashbots/cvm-reverse-proxy/cmd/attested-get
cargo install --git https://github.com/flashbots/attested-tls-proxy attested-tls-proxy
# optionally add --tag <version number of latest release>
```

attested-get \
--addr=https://rpc.buildernet.org:7936/cert \
--out-measurements=measurements.json \
--out-response=builder-cert.pem
Alternatively see the [releases page](https://github.com/flashbots/attested-tls-proxy/releases) to install from pre-built x86 binary or debian package.

```
attested-tls-proxy get-tls-cert \
--allowed-remote-attestaton-type tdx \
--out-measurements measurements.json \
rpc.buildernet.org:7936/cert > builder-cert.pem
```

Here's an example command for an attested request to the Flashbots BuilderNet node, matching expected measurements from https://measurements.buildernet.org:

```
attested-get \
--addr=https://rpc.buildernet.org:7936/cert \
--expected-measurements=https://measurements.buildernet.org \
--out-response=builder-cert.pem
attested-tls-proxy get-tls-cert \
--measurements-file https://measurements.buildernet.org \
rpc.buildernet.org:7936/cert > builder-cert.pem
```

You can then use the `builder-cert.pem` file to verify the attested TLS certificate in your future requests to BuilderNet.
8 changes: 4 additions & 4 deletions docs/network-ports.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Ports open for connections from outside the TDX instance.
| ---- | ---------------- | --------------------------------------------------------------------------- | ----------------------------------------------------- |
| 80 | TCP (HTTP) | HAProxy | Permanent redirect to HTTPS |
| 443 | TCP (HTTPS) | HAProxy for [orderflow-proxy](https://github.com/flashbots/orderflow-proxy) | Orderflow from operator, users, wallets, etc. |
| 7936 | TCP (HTTPS/aTLS) | [cvm-proxy](https://github.com/flashbots/cvm-reverse-proxy) | aTLS attested channel to serve local TLS certificate. |
| 7936 | TCP (HTTPS/aTLS) | [attested-tls-proxy](https://github.com/flashbots/attested-tls-proxy) | Attested TLS channel to serve local TLS certificate. |

**Selective access**

Expand All @@ -43,10 +43,10 @@ Ports open to requests from inside the TDX instance only.

| Port | Protocol | Service | Use |
| ----- | ---------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 14727 | TCP (HTTP) | HAProxy | Serving `GET /cert` REST API (which is used by cvm-proxy on port 7936). |
| 14727 | TCP (HTTP) | HAProxy | Serving `GET /cert` REST API (which is used by attested-tls-proxy on port 7936). |
| 5542 | TCP (HTTP) | [orderflow-proxy](https://github.com/flashbots/orderflow-proxy) | System orderflow, via HAProxy on port 5544. |
| 5543 | TCP (HTTP) | [orderflow-proxy](https://github.com/flashbots/orderflow-proxy) | User orderflow, via HAProxy on port 443. |
| 7937 | TCP (HTTP) | [cvm-proxy](https://github.com/flashbots/cvm-reverse-proxy) | Proxy for requests to Flashbots infra (BuilderHub) using client-aTLS-attestation. Used to retrieve secrets and configuration, a list of peers, and for services to register their public keys. |
| 7937 | TCP (HTTP) | [attested-tls-proxy](https://github.com/flashbots/attested-tls-proxy) | Proxy for requests to Flashbots infra (BuilderHub) using client-aTLS-attestation. Used to retrieve secrets and configuration, a list of peers, and for services to register their public keys. |
| 8645 | TCP | [rbuilder](https://github.com/flashbots/rbuilder) | JSON-RPC API (requests are sent from orderflow-proxy). |
| 6069 | TCP | [rbuilder](https://github.com/flashbots/rbuilder) | Prometheus telemetry. |
| 6070 | TCP | [rbuilder](https://github.com/flashbots/rbuilder) | Redacted telemetry and health check |
Expand All @@ -71,6 +71,6 @@ On the firewall, these ports should be opened up for either private or public ac
| 30303 | Reth | **Public** | Execution network peering |
| 80 | HAProxy | **Public** | Redirect to HTTPS |
| 443 | Orderflow Proxy (via HAProxy) | Operator, optionally for users | Receive orderflow from operator, users, wallets. |
| 7936 | cvm-proxy | Operator, optionally for users | Serve the local TLS certificate through an attested channel (aTLS). |
| 7936 | attested-tls-proxy | Operator, optionally for users | Serve the local TLS certificate through an attested channel (aTLS). |
| 3535 | Operator Api | Operator | Admin interface |
| 14192 | SSH | Operator | SSH access to the instance |
2 changes: 1 addition & 1 deletion docs/open-source.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ BuilderNet is running open source software and infrastructure.
| [github.com/sigp/lighthouse](https://github.com/sigp/lighthouse) | CL client |
| [github.com/paradigmxyz/reth/](https://github.com/paradigmxyz/reth/) | EL client |
| [github.com/flashbots/system-api](https://github.com/flashbots/system-api) | Interface between operators and services inside the TDX instance |
| [github.com/flashbots/cvm-reverse-proxy](https://github.com/flashbots/cvm-reverse-proxy) | For verifying TDX measurements using attestations |
| [github.com/flashbots/attested-tls-proxy](https://github.com/flashbots/attestd-tls-proxy) | For verifying TDX measurements using attestations |
| [github.com/flashbots/buildernet-orderflow-proxy](https://github.com/flashbots/buildernet-orderflow-proxy) | Receiving and multiplexing orderflow |

---
Expand Down
4 changes: 2 additions & 2 deletions docs/os-services-builds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ These are the main services running inside an instance:
| [github.com/sigp/lighthouse](https://github.com/sigp/lighthouse) | CL client |
| [github.com/paradigmxyz/reth/](https://github.com/paradigmxyz/reth/) | EL client |
| [github.com/flashbots/system-api](https://github.com/flashbots/system-api) | Interface between operators and services inside the TDX instance |
| [github.com/flashbots/cvm-reverse-proxy](https://github.com/flashbots/cvm-reverse-proxy) | For verifying TDX measurements using attestations |
| [github.com/flashbots/attested-tls-proxy](https://github.com/flashbots/attested-tls-proxy) | For verifying TDX measurements using attestations |
| [github.com/flashbots/buildernet-orderflow-proxy](https://github.com/flashbots/buildernet-orderflow-proxy) | Receiving and multiplexing orderflow |

Additional software that runs inside the TDX instance includes cron, time synchronization, utilities for mounting the encrypted disk and a Reth database downloader (for fast chain syncs).
Expand Down Expand Up @@ -80,4 +80,4 @@ BuilderNet node TDX VM images can be fully reproducibly built. The overall build

The main build process is defined in these manifests: https://github.com/flashbots/yocto-manifests.

To get started, follow the “Getting Started” instructions in the [yocto-manifests README](https://github.com/flashbots/yocto-manifests?tab=readme-ov-file#getting-started).
To get started, follow the “Getting Started” instructions in the [yocto-manifests README](https://github.com/flashbots/yocto-manifests?tab=readme-ov-file#getting-started).
Loading