메인 콘텐츠로 건너뛰기
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를 구성합니다.
리소스최소권장비고
CPU2 코어, Intel SGX4+ 코어Xeon Platinum 8370C (Ice Lake-SP) 또는 이상
RAM8 GB16 GBEnclave가 4 GB EPC 사용; 호스트는 story + geth를 위한 나머지 필요
EPC Memory4 GB8 GBenclave_size (4 GB) 이상이어야 함
Disk50 GB128 GB+커널 데이터는 작음 (~100 MB)
지원되는 클라우드 인스턴스 (Azure):
인스턴스 타입vCPUsRAMEPC비고
Standard_DC1s_v318 GB4 GB최소 EPC 충족하나 RAM이 빠듯함
Standard_DC2s_v3216 GB8 GB최소 권장
Standard_DC4s_v3432 GB16 GB권장
Standard_DC8s_v3864 GB32 GB고부하 Validator
Standard_DC16s_v3+16+128+ GB64+ GBDC48s_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(코드 커밋먼트) 값을 생성하기 위해 아래의 정확히 동일한 버전을 반드시 사용해야 합니다.
컴포넌트필수 버전이유
Ubuntu24.04 LTS라이브러리 경로가 MRENCLAVE에 측정됨
Go1.24.0다른 버전은 다른 바이너리를 생성함
Gramine1.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_idCL 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 fileBIOS에서 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 requiredconfig의 witness_addrs에 최소 2개 항목 추가

DKG 등록 실패

오류해결 방법
no kernel client for code commitmentstory 로그에서 Connected to kernel 확인; MRENCLAVE가 온체인 화이트리스트와 일치하는지 확인
execution revertedDCAP 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)에 네트워크 액세스가 필요합니다.

추가 정보

빌드 환경

컴포넌트버전
Ubuntu24.04.4 LTS
Go1.24.0
Gramine1.9 (apt)
gramine-ratls-dcap1.9
story-kernelv0.1.0 (tag)
cb-mpcv0.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를 재시작하세요. 현재 라운드가 종료되면 참여가 중단됩니다.