DKG는 현재 Aeneid 테스트넷에서만 사용할 수 있습니다. 메인넷 지원은 향후 릴리스에서 제공될 예정입니다.
v1.6.0 업그레이드부터, Validator는 DKG(Distributed Key Generation) 위원회에 참여할 수 있습니다. 참여하려면 story-kernel을 실행해야 하며, 이는 Validator 노드와 함께 Intel SGX enclave 내부에서 실행되는 TEE 클라이언트입니다.
DKG 참여는 선택 사항입니다. story.toml에서 dkg.enable = false로 유지하면 DKG 위원회에 참여하지 않고 Validator를 계속 운영할 수 있습니다.
참여 전 알아두어야 할 사항:
- SGX 하드웨어 필수: 머신에 Intel SGX 지원이 있어야 합니다
- 활성 DKG 위원회 멤버인 동안에는 자기 위임 해제(self-undelegation)가 차단됩니다. 현재 DKG 라운드가 종료될 때까지 자신의 위임 지분을 해제할 수 없습니다(프로덕션 파라미터 기준 약 7일). 다른 위임자는 영향을 받지 않습니다.
- 커널이 다운되어도 Validator는 정상적으로 블록을 계속 생성합니다. 커널이 재시작되고 현재 라운드가 종료되기 전에 노드가 성공적으로 finalize되면 해당 라운드에 다시 참여할 수 있으며, 그렇지 않으면 다음 라운드에 다시 참여합니다.
하드웨어 요구사항
story-kernel은 전용 Enclave Page Cache (EPC) 메모리를 필요로 하는 SGX enclave 내부에서 실행됩니다. Gramine manifest는 Go 런타임과 DKG 암호화 연산을 위한 4 GB enclave를 구성합니다.
| 리소스 | 최소 | 권장 | 비고 |
|---|
| CPU | 2 코어, Intel SGX | 4+ 코어 | Xeon Platinum 8370C (Ice Lake-SP) 또는 이상 |
| RAM | 8 GB | 16 GB | Enclave가 4 GB EPC 사용; 호스트는 story + geth를 위한 나머지 필요 |
| EPC Memory | 4 GB | 8 GB | enclave_size (4 GB) 이상이어야 함 |
| Disk | 50 GB | 128 GB+ | 커널 데이터는 작음 (~100 MB) |
지원되는 클라우드 인스턴스 (Azure):
| 인스턴스 타입 | vCPUs | RAM | EPC | 비고 |
|---|
| Standard_DC1s_v3 | 1 | 8 GB | 4 GB | 최소 EPC 충족하나 RAM이 빠듯함 |
| Standard_DC2s_v3 | 2 | 16 GB | 8 GB | 최소 권장 |
| Standard_DC4s_v3 | 4 | 32 GB | 16 GB | 권장 |
| Standard_DC8s_v3 | 8 | 64 GB | 32 GB | 고부하 Validator |
| Standard_DC16s_v3+ | 16+ | 128+ GB | 64+ GB | DC48s_v3까지 (48 vCPUs, 384 GB, 256 GB EPC) |
Bare metal도 지원됩니다: BIOS에서 SGX가 활성화된 모든 Intel 서버. dmesg | grep "sgx: EPC section"로 EPC 크기를 확인하세요.
AMD SEV-SNP 인스턴스(예: Azure DCasv5) 및 ARM 인스턴스는 현재 지원되지 않습니다.
소프트웨어 요구사항
모든 Validator는 동일한 MRENCLAVE(코드 커밋먼트) 값을 생성하기 위해 아래의 정확히 동일한 버전을 반드시 사용해야 합니다.
| 컴포넌트 | 필수 버전 | 이유 |
|---|
| Ubuntu | 24.04 LTS | 라이브러리 경로가 MRENCLAVE에 측정됨 |
| Go | 1.24.0 | 다른 버전은 다른 바이너리를 생성함 |
| Gramine | 1.9 | 소스에서 빌드가 아닌 apt로 설치해야 함 |
설정 가이드
1단계: SGX 지원 확인
ls /dev/sgx_enclave && echo "SGX available" || echo "SGX NOT available"
/dev/sgx_enclave가 존재하지 않으면 SGX가 지원되지 않거나 BIOS/클라우드 설정에서 활성화되지 않은 것입니다.
2단계: 의존성 설치
Intel SGX SDK 및 DCAP
sudo mkdir -p /etc/apt/keyrings
wget -qO- https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key \
| sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64]\
https://download.01.org/intel-sgx/sgx_repo/ubuntu noble main" \
| sudo tee /etc/apt/sources.list.d/intel-sgx.list
sudo apt update
sudo apt install -y build-essential cmake libssl-dev \
libsgx-dcap-default-qpl libsgx-enclave-common libsgx-quote-ex
PCCS 구성
/etc/sgx_default_qcnl.conf를 편집하세요:
{
"pccs_url": "https://global.acccache.azure.net/sgx/certification/v4/",
"collateral_service": "https://global.acccache.azure.net/sgx/certification/v4/"
}
Gramine 1.9 설치
sudo curl -fsSLo /usr/share/keyrings/gramine-keyring.gpg \
https://packages.gramineproject.io/gramine-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg]\
https://packages.gramineproject.io/ noble main" \
| sudo tee /etc/apt/sources.list.d/gramine.list
sudo apt update
sudo apt install -y gramine=1.9
3단계: Story-Kernel 빌드
git clone https://github.com/piplabs/story-kernel.git
cd story-kernel
git checkout <release-tag> # 업그레이드 공지의 태그 사용
make setup-cbmpc # 최초 1회만
make build-with-cpp
make all-gramine
출력에서 MRENCLAVE 값을 확인하세요:
Code Commitment: mr_enclave: <64-char hex>
모든 Validator는 동일한 MRENCLAVE를 생성해야 합니다. 다르다면, 정확히 동일한 커밋, OS 버전, Go 버전, Gramine 버전을 사용했는지 확인하세요.
4단계: 데이터 디렉토리 설정
sudo mkdir -p /opt/story-kernel
sudo chown $USER:$USER /opt/story-kernel
5단계: 초기화 및 구성
초기화
gramine-sgx story-kernel init --home /opt/story-kernel
/opt/story-kernel/config.toml을 편집하세요:
log-level = "info"
[grpc]
listen_addr = ":50051"
[light_client]
chain_id = "devnet-1"
rpc_addr = "http://localhost:26657"
primary_addr = "http://localhost:26657"
witness_addrs = ["http://<other_validator_1>:26657", "http://<other_validator_2>:26657"]
trusted_height = <recent_block_height>
trusted_hash = "<recent_block_hash>"
신뢰할 수 있는 블록은 지난 2주 이내여야 합니다. 라이트 클라이언트는 신뢰 기간을 사용하므로, 신뢰 블록이 오래되었다면 헤더 검증이 실패합니다.
최근 신뢰 블록 가져오기:
curl -s 'http://localhost:26657/block' | python3 -c "
import json, sys
r = json.load(sys.stdin)['result']
print(f'trusted_height = {r[\"block\"][\"header\"][\"height\"]}')
print(f'trusted_hash =\"{r[\"block_id\"][\"hash\"]}\"')
"
| 필드 | 설명 |
|---|
chain_id | CL chain ID: Aeneid의 경우 devnet-1 |
witness_addrs | 라이트 클라이언트 교차 검증을 위한 최소 2개의 CometBFT RPC 엔드포인트. 동일한 주소가 반복될 수 있으나(예: ["http://x:26657", "http://x:26657"]), 보안 강화를 위해 서로 다른 2개의 Validator를 사용하는 것을 권장합니다. 동일 네트워크에 있는 경우 내부/사설 IP를 사용하세요. |
6단계: Story 클라이언트 구성
~/.story/story/config/story.toml에 다음 변경 사항을 적용하세요:
engine-chain-id 추가 (없는 경우)
engine-chain-id = 1315 # Aeneid의 경우
DKG 옵션 섹션 추가
#######################################################################
### DKG Options ###
#######################################################################
[dkg]
# Enable defines if the DKG client is enabled or not.
enable = true
# Comma-separated list of story-kernel (TEE) endpoints.
kernel-endpoints = ["127.0.0.1:50051"]
# The RPC endpoint of execution layer.
engine-rpc-endpoint = "http://127.0.0.1:8545"
# TEE enclave type identifier (1 for SGX).
enc-type = 1
# TLS configuration for kernel gRPC connections (optional).
#kernel-tls-ca-file = "/path/to/ca.crt"
#kernel-tls-cert-file = "/path/to/client.crt"
#kernel-tls-key-file = "/path/to/client.key"
7단계: 서비스 시작
시작 순서가 중요합니다. 커널은 라이트 클라이언트 초기화를 위해 CometBFT RPC(포트 26657)가 필요하므로, story-kernel은 체인이 실행된 후에 시작하세요.
Story-Kernel 시작
sudo tee /etc/systemd/system/story-kernel.service > /dev/null <<EOF
[Unit]
Description=DATA Foundation DKG TEE Service
After=network.target
[Service]
User=$USER
WorkingDirectory=$HOME/story-kernel
ExecStart=/usr/bin/gramine-sgx story-kernel
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable story-kernel
sudo systemctl start story-kernel
SGX enclave 로딩에는 1-3분이 걸립니다. 프로세스가 “Parsing TOML manifest file”에서 멈춘 것처럼 보일 수 있으나, 이는 정상입니다.
DATA Foundation 재시작
sudo systemctl restart story
8단계: 검증
커널 실행 확인
sudo lsof -i :50051 | grep LISTEN
journalctl -u story-kernel --no-pager -n 20
# 다음을 찾으세요: "gRPC server is started: :50051"
DATA Foundation이 커널에 연결됨
journalctl -u story --no-pager -n 100 | grep "Connected to kernel"
# 예상 결과: Connected to kernel endpoint endpoint=127.0.0.1:50051 code_commitment=<mrenclave>
DKG 등록
journalctl -u story --no-pager | grep "DKG_REG_STATUS_VERIFIED"
문제 해결
커널이 시작되지 않음
| 오류 | 해결 방법 |
|---|
/dev/sgx_enclave: No such file | BIOS에서 SGX를 활성화하거나 SGX 지원 VM 사용 |
| ”Parsing TOML manifest file”에서 멈춤 | 정상, 1-3분 대기 |
config not found | /opt/story-kernel/config.toml에 config가 존재하는지 확인 |
height requested is too high | /opt/story-kernel/light_client/를 삭제하고 새 신뢰 블록으로 재시작 |
at least 2 witness addresses required | config의 witness_addrs에 최소 2개 항목 추가 |
DKG 등록 실패
| 오류 | 해결 방법 |
|---|
no kernel client for code commitment | story 로그에서 Connected to kernel 확인; MRENCLAVE가 온체인 화이트리스트와 일치하는지 확인 |
execution reverted | DCAP attestation 실패: SGX 설정 및 PCCS config 확인 |
Failed to generate the sealed key | 자세한 내용은 커널 로그 확인 |
라이트 클라이언트 문제
sudo systemctl stop story-kernel
rm -rf /opt/story-kernel/light_client/
# config.toml에서 trusted_height 및 trusted_hash 업데이트
sudo systemctl start story-kernel
중요 사항
자기 위임 해제 제한
Validator가 활성 DKG 라운드의 finalized 멤버인 동안 자기 위임 해제는 차단됩니다. 이는 위원회 멤버가 라운드 중간에 이탈하여 임계값 암호화를 손상시키는 것을 방지합니다.
- 자기 위임 해제만 차단됨; 다른 위임자는 정상적으로 unstake 가능
- 현재 라운드가 종료되면 제한이 해제됨
- 프로덕션 파라미터 기준 전체 DKG 라운드는 약 7일 소요
별도 머신에서 커널 실행
story-kernel은 전용 SGX 머신에서 실행할 수 있습니다. story.toml에서 kernel-endpoints를 업데이트하세요:
kernel-endpoints = ["<sgx-machine-ip>:50051"]
SGX 머신은 CometBFT RPC(포트 26657)에 네트워크 액세스가 필요합니다.
추가 정보
빌드 환경
| 컴포넌트 | 버전 |
|---|
| Ubuntu | 24.04.4 LTS |
| Go | 1.24.0 |
| Gramine | 1.9 (apt) |
| gramine-ratls-dcap | 1.9 |
| story-kernel | v0.1.0 (tag) |
| cb-mpc | v0.0.1-alpha |
Enclave 측정값
아래 측정값은 story-kernel 릴리스 v0.1.0에 해당합니다. story-kernel 또는 측정된 빌드 입력이 업그레이드되면 변경될 수 있습니다.
MRENCLAVE: 6b2fb25e0084ad6ecbf6cfcefe09e2fa0fca2b84092f72c01f8fe98e9d7db5cd
Binary hash: 320a744e87426e36de63ebc8c7ff3af23e00ac7b29ad6093acdafd0bb029ca36
FAQ
Validator를 운영하는 데 SGX가 필요한가요?
아니요. SGX는 DKG 위원회 참여에만 필요합니다. SGX 없이 실행하려면 dkg.enable = false로 설정하세요.
커널이 다운되면 어떻게 되나요?
Validator는 계속 블록을 생성합니다. 커널이 재시작되고 현재 DKG 라운드가 종료되기 전에 노드가 성공적으로 finalize되면 해당 라운드에 다시 참여할 수 있으며, 그렇지 않으면 다음 라운드에 다시 참여합니다.
MRENCLAVE는 무엇인가요?
SGX enclave 콘텐츠의 암호화 해시입니다. 모든 Validator는 동일한 DKG 위원회에 참여하기 위해 동일한 값을 생성해야 합니다.
참여 후 옵트아웃할 수 있나요?
가능합니다. dkg.enable = false로 설정하고 story를 재시작하세요. 현재 라운드가 종료되면 참여가 중단됩니다.