Skip to content

Commit 837ccff

Browse files
lapetslapets
committed
feat: initial high-level Blacklight architecture diagram
1 parent 75cc41f commit 837ccff

File tree

3 files changed

+96
-9
lines changed

3 files changed

+96
-9
lines changed

‎docs/blacklight/learn/architecture.md‎

Lines changed: 90 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,101 @@
22

33
## Overview
44

5-
Nillion Blacklight is a decentralised verification network designed to continuously verify workloads running inside Trusted Execution Environments (TEEs). The system is composed of three core components that work together to provide ongoing, credibly neutral verification.
5+
Nillion Blacklight is a decentralised verification network designed to continuously verify workloads running inside trusted execution environments (TEEs). The system is composed of three core components that work together to provide ongoing, credibly neutral verification.
66

77
* TEE Operators run workloads inside TEEs and submit proofs of liveness (that we call heartbeat transactions - HTXs).
88
* [**Nillion's Ethereum L2**](/blacklight/verify/network) coordinates verification, consensus, and rewards. Verification coordination is realised by the L2 assigning Blacklight nodes HTXs they should verify.
99
* Blacklight nodes independently challenge and verify TEE attestations.
1010

11+
```mermaid
12+
%%{
13+
init: {
14+
'theme': 'base',
15+
'themeVariables': {
16+
'fontSize': '18px',
17+
'primaryTextColor': '#000000',
18+
'primaryBorderColor': '#000000',
19+
'secondaryBorderColor': '#000000',
20+
'tertiaryBorderColor': '#000000',
21+
'edgeLabelBackground': '#DFDFDF'
22+
}
23+
}
24+
}%%
25+
graph TD
26+
27+
subgraph TEE_OPERATORS [<b style="color:#000000;">TEE Operators</b>]
28+
direction LR
29+
TEE_1[<b>TEE</b>]
30+
-.-TEE_2[<b>TEE</b>]
31+
-.-TEE_3[<b>TEE</b>]
32+
-.-TEE_4[<b>TEE</b>]
33+
-.-TEE_5[<b>TEE</b>]
34+
end
35+
TEE_OPERATORS:::COMPONENT_TOP
36+
classDef COLLECTION color:#888888,font-weight:bold
37+
TEE_OPERATORS:::COLLECTION
38+
style TEE_OPERATORS fill:#f5f5f5,stroke:#cccccc
39+
classDef TEE fill:#ffffff,stroke:#cccccc,color:#000000
40+
TEE_1:::TEE
41+
TEE_2:::TEE
42+
TEE_3:::TEE
43+
TEE_4:::TEE
44+
TEE_5:::TEE
45+
46+
subgraph L2 [<b>Nillion Ethereum L2</b>]
47+
subgraph CONTRACTS [<b style="font-size:14px;">Smart Contracts</b>]
48+
STAKING[<b>Staking</b>]
49+
-.-SELECTION[<b>Selection</b>]
50+
-.-CONSENSUS[<b>Consensus Evaluation</b>]
51+
-.-REWARDS[<b>Rewards</b>]
52+
end
53+
end
54+
L2:::COMPONENT_LEFT
55+
style L2 fill:#f5f5f5,stroke:#cccccc,color:#000000
56+
style CONTRACTS fill:#f5f5f5,stroke:#cccccc,color:#000000
57+
classDef CONTRACT fill:#ffffff,stroke:#cccccc,color:#000000,font-size:12px
58+
STAKING:::CONTRACT
59+
SELECTION:::CONTRACT
60+
CONSENSUS:::CONTRACT
61+
REWARDS:::CONTRACT
62+
63+
subgraph BLACKLIGHT_NODES [<b>Blacklight Nodes</b>]
64+
direction LR
65+
NODE_1[<b>Node</b>]
66+
-.-NODE_2[<b>Node</b>]
67+
-.-NODE_3[<b>Node</b>]
68+
-.-NODE_4[<b>Node</b>]
69+
-.-NODE_5[<b>Node</b>]
70+
-.-NODE_6[<b>Node</b>]
71+
-.-NODE_7[<b>Node</b>]
72+
end
73+
BLACKLIGHT_NODES:::COMPONENT_RIGHT
74+
style BLACKLIGHT_NODES fill:#f5f5f5,stroke:#cccccc,color:#000000
75+
classDef NODE fill:#ffffff,stroke:#cccccc,color:#000000
76+
NODE_1:::NODE
77+
NODE_2:::NODE
78+
NODE_3:::NODE
79+
NODE_4:::NODE
80+
NODE_5:::NODE
81+
NODE_6:::NODE
82+
NODE_7:::NODE
83+
84+
classDef COMPONENT_TOP padding-left:10px,padding-right:410px
85+
classDef COMPONENT_LEFT stroke:#cccccc,padding-left:10px,padding-right:410px
86+
classDef COMPONENT_RIGHT stroke:#cccccc,padding-left:10px,padding-right:660px
87+
88+
TEE_OPERATORS --->|HTXs| L2
89+
L2 --->|assignments| BLACKLIGHT_NODES
90+
L2 --->|rewards| BLACKLIGHT_NODES
91+
TEE_OPERATORS --->|attestations| BLACKLIGHT_NODES
92+
BLACKLIGHT_NODES --->|signed verifications| L2
93+
94+
linkStyle default stroke-width:3px,stroke:#5555CC
95+
linkStyle 0,1,2,3,4,5,6,7,8,9,10,11,12 stroke-width:0px !important,stroke:transparent !important
96+
```
97+
98+
<br/>
99+
11100
Together, these components enable continuous, decentralised verification of TEE-backed workloads. In doing so, they act as a credibly neutral trust layer for TEEs.
12101

13102
The central concept underpinning Nillion Blacklight is that of the heartbeat transaction (HTX), a periodic, workload-level proof of liveness submitted by TEE operators that signals a workload is still running inside a real enclave and is ready to be independently verified by the network.

‎docs/blacklight/learn/verification.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,22 @@
11
# Verification
22

3-
This page describes the verification protocol from Nillion Blacklight.
4-
For an overview of the system architecture and its three core components (TEE Operators, Nillion's Ethereum L2, and Blacklight Nodes), see the [architecture](/blacklight/learn/architecture) page.
3+
This page describes the verification protocol utilized within Nillion Blacklight. For an overview of the system architecture and its three core components (TEE operators, Nillion's Ethereum L2, and Blacklight nodes), see the [architecture page](/blacklight/learn/architecture).
54

65

76
## TEE Operators
87

9-
Developers run their workloads inside Trusted Execution Environments (TEEs), such as [nilCC](/blind-computer/build/compute/overview).
8+
Developers run their workloads inside trusted execution environments (TEEs), such as [nilCC](/blind-computer/build/compute/overview).
109
For each active workload, the TEE operators periodically submit heartbeat transactions (HTXs) to [Nillion's Ethereum L2](/blacklight/verify/network) at custom intervals (e.g., one every hour).
1110

1211
### Heartbeat Transaction (HTX)
1312

14-
Each HTX serves as a proof of liveness, asserting that:
13+
Each HTX serves as a proof of liveness, asserting the three facts below.
14+
1515
- The workload is still running inside a real TEE enclave
1616
- The workload is ready to be independently verified by the network
1717
- The workload maintains its privacy and integrity guarantees
1818

19-
An HTX contains the metadata required for Blacklight nodes to independently verify a TEE workload.
20-
The following example illustrates the structure of an HTX:
19+
An HTX contains the metadata required for Blacklight nodes to independently verify a TEE workload. The below example illustrates the structure of an HTX.
2120

2221
```json
2322
{
@@ -39,7 +38,7 @@ The following example illustrates the structure of an HTX:
3938
}
4039
```
4140

42-
Key components of the HTX:
41+
The key components of an HTX are enumerated below.
4342

4443
- **`provider`**: Identifies the TEE provider (e.g., "nillion", "phala", etc)
4544
- **`version`**: HTX protocol version

‎docs/blind-computer/learn/architecture.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,6 @@ When using the blind computer, developers rely on two components: the **Petnet**
5353
NILDB:::BLIND_MODULE
5454
NILAI:::BLIND_MODULE
5555
56-
5756
subgraph NILCHAIN [<b>Nillion L2</b>]
5857
subgraph MECHANISMS [<b>Mechanisms</b>]
5958
direction LR

0 commit comments

Comments
 (0)