Posts on Jeongseup Blog

Transformer에서 MCP와 Skill까지: AI 에이전트는 어떻게 생각하고 행동하는가?

Sat, 19 Sep 2026 00:00:00 +0000

요약:
CNN/RNN의 파편화를 끝낸 Transformer의 대통합, “방 안의 뇌"였던 LLM에게 손발을 달아주려다 실패한 1세대 플러그인, 그 한계를 극복한 오픈 표준 MCP(Model Context Protocol), 그리고 토큰 낭비 없이 전문 전술을 주입하는 **스킬(Skill)**의 진화 과정을 실제 통신 패킷과 시각화 아키텍처로 쉽게 풀어봅니다.

1. 프롤로그: 모든 데이터가 하나로 통합되던 순간 (Transformer 혁명)

과거 딥러닝 시절에는 데이터 형태에 따라 완전히 다른 모델과 수학 공식을 써야 했습니다.

이미지: 픽셀 격자 위를 훑는 3×3 필터 행렬 연산 (CNN)
텍스트: 이전 단어의 기억을 다음 상태로 넘기는 재귀 루프 (RNN/LSTM)

하지만 2017년 Transformer의 등장 이후, AI는 세상의 모든 데이터를 단 하나의 포맷, 즉 **‘토큰(Token)’**으로 통일해 버렸습니다.

💡 Example: 서로 다른 데이터가 토큰으로 바뀌는 실제 모습

① 텍스트의 토큰화 (BPE Tokenization)

1

"def calculate(price):" ──► [721, 14205, 7, 4923, 1313]

② 이미지의 토큰화 (Vision Transformer, ViT)

224×224 픽셀 이미지를 16×16 픽셀짜리 바둑판 조각(패치) 196개로 자른 뒤 일렬로 펼쳐 단어처럼 취급합니다.

1

[16x16 픽셀 패치 1개] ──► 1차원 펼치기 (768차원 실수 벡터) ──► [0.24, -0.81, 0.05, ...]

③ 결과: 다차원 공간에서의 “공통 의미 좌표” 수렴

1
2
3


Cosine Similarity( "고양이", "cat" ) ≒ 0.96 (거의 일치)
Cosine Similarity( "고양이", [고양이 털 사진 16x16 패치] ) ≒ 0.91 (의미 일치!)
Cosine Similarity( "고양이", "class Cat(Animal):" ) ≒ 0.88 (코드와도 일치!)

🏛️ Architecture 1: Transformer Multimodal Tokenization & Shared Latent Space

아래 다이어그램은 글자, 이미지 패치, 오디오가 단일 트랜스포머 어텐션 계층을 거쳐 공통 잠재 공간(Shared Latent Space)으로 수렴하는 구조를 보여줍니다.

🔍 인터랙티브 다이어그램 전체화면으로 보기 (줌/팬 & 가이드 뷰 지원)

📷 정적 다이어그램 이미지로 보기

2. “방 안의 천재"에게 손발을 달아주려던 1세대 시도: 플러그인(Plugin)의 실패

똑똑해진 LLM도 혼자서는 방 안을 벗어날 수 없었습니다. 모델은 오직 “텍스트를 받아 다음 텍스트를 출력하는 수학 함수"였기 때문입니다. 이때 등장한 1세대 시도가 **2023년의 ‘ChatGPT Plugins’**였습니다.

💡 Example: 과거 플러그인의 구조적 한계 (`ai-plugin.json`)

1
2
3
4
5


{
 "schema_version": "v1",
 "name_for_model": "autocad",
 "api": { "type": "openapi", "url": "https://api.my-cloud.com/openapi.yaml" }
}

1
2
3
4
5
6
7
8
9


[사용자] "내 맥북에 켜진 AutoCAD에 사각형 그려줘."
 │
 ▼ (1) ChatGPT 클라우드가 플러그인 API 호출 시도
OpenAI Server ──► HTTP POST https://api.my-cloud.com/draw
 │
 ▼ (2) "내 맥북의 로컬 AutoCAD를 어떻게 부르지?"
클라우드 서버는 사용자의 개인 맥북 사설망(192.168.0.x)이나 COM 포트에 접속 불가!
 │
 ❌ 결과: 로컬 PC 제어 불가능 (클라우드 SaaS만 호출 가능)

3. 2세대 표준화 혁명: MCP (Model Context Protocol) — AI의 USB-C

Anthropic이 오픈소스로 공개한 MCP는 도구를 클라우드가 아닌 사용자의 로컬 컴퓨터에서 독립 프로세스로 실행하도록 하여 이 한계를 정면으로 돌파했습니다.

💡 Example: AI와 로컬 앱 사이의 실제 통신 패킷 (JSON-RPC)

① AI ➔ MCP Server (Request):

1
2
3
4
5
6
7
8
9


{
 "jsonrpc": "2.0",
 "method": "tools/call",
 "params": {
 "name": "draw_line",
 "arguments": { "start": [0, 0], "end": [500, 0], "layer": "Wall" }
 },
 "id": 1
}

② MCP Server ➔ 로컬 AutoCAD 실행 후 AI 응답 (Response):

1
2
3
4
5
6
7


{
 "jsonrpc": "2.0",
 "result": {
 "content": [{ "type": "text", "text": "Success: Line Entity #A284 created on 'Wall'." }]
 },
 "id": 1
}

4. 손발이 생겼는데 왜 또 ‘스킬(Skill)‘이 필요할까?

도구(MCP)만 쥐어준다고 일을 잘하지는 않습니다.
회사 규칙(Git Flow), 커밋 컨벤션(Conventional Commits), 도면 레이어 규칙을 모르면 엉뚱하게 도구를 쓰기 때문입니다.

스킬은 모든 규칙을 시스템 프롬프트에 넣어 토큰을 낭비하는 대신, **필요한 순간에만 전문 매뉴얼(SKILL.md)을 대화 컨텍스트에 동적 주입(Progressive Disclosure)**합니다.

🏛️ Architecture 2: Plugin vs MCP vs Skill 엔드투엔드 워크플로우

아래 다이어그램은 상단의 Skill 주입 흐름, 중앙의 에이전트 판단, 그리고 하단의 **MCP 로컬 실행 (AutoCAD/Figma)**과 Legacy Plugin의 차이를 한눈에 보여줍니다.

🔍 인터랙티브 다이어그램 전체화면으로 보기 (Trace 애니메이션 및 뷰 전환 지원)

📷 정적 다이어그램 이미지로 보기

5. 실제 프롬프트 백엔드에서는 무슨 일이 일어나는가?

사용자가 채팅창에 입력한 글은 단 한 줄이지만, 런타임은 배후에서 스킬을 결합하여 거대한 프롬프트로 확장(Augment)해 LLM에 전달합니다.

사용자가 입력한 것:

“새로운 로그인 기능 커밋하고 PR 올려줘. /git-workflow”

실제 LLM API로 전달되는 HTTP Payload:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


{
 "model": "claude-3-7-sonnet",
 "messages": [
 {
 "role": "system",
 "content": "당신은 AI 코딩 어시스턴트입니다..."
 },
 {
 "role": "system",
 "name": "injected_skill_instructions",
 "content": "=== [DYNAMIC SKILL LOADED: git-workflow] ===\n1. 커밋 전 반드시 npm test 통과 여부를 검증할 것.\n2. 커밋 메시지는 'feat(auth): ...' 형식을 준수할 것.\n3. main에 직접 푸시하지 말고 feature/ 브랜치를 생성할 것.\n============================================"
 },
 {
 "role": "user",
 "content": "새로운 로그인 기능 커밋하고 PR 올려줘."
 }
 ],
 "tools": [{ "name": "mcp_git_cli", "description": "로컬 git 명령어 실행" }]
}

6. 결론: 2026 에이전트 아키텍처의 완성 공식

$$\text{완전한 AI 에이전트} = \text{Transformer (두뇌)} + \text{Skill (전술/SOP)} + \text{MCP (손발/도구)}$$

Transformer: 텍스트, 코드, 이미지를 단일 토큰 공간에서 해석하는 거대한 만능 두뇌
Skill: 토큰을 낭비하지 않고 필요할 때만 전문가 매뉴얼을 뇌에 주입하는 동적 전술 지침(SOP)
MCP: 내 컴퓨터의 OS, 로컬 파일, CAD, Figma, DB를 직접 조종하는 표준화된 인터페이스 (USB-C)

이 세 요소가 결합될 때 비로소 모델은 단순한 챗봇을 넘어, 현실 세계의 소프트웨어와 엔지니어링 문제를 스스로 해결하는 진정한 에이전트로 진화합니다.

AWS KMS로 Ethereum 트랜잭션 서명하기: 타원곡선의 어두운 면

Thu, 19 Mar 2026 00:00:00 +0000

AWS KMS의 kms:Sign과 kms:GetPublicKey 두 권한이 왜 모두 필요한지, Ethereum 서명의 내부 동작을 따라가며 이해한 기록.

배경: 왜 AWS KMS로 서명하는가?

Ethereum 트랜잭션에 서명하려면 개인키가 필요하다. 보통은 keystore 파일이나 환경변수에 평문으로 저장하지만, 프로덕션 환경에서는 보안 위험이 크다.

AWS KMS는 개인키를 HSM(Hardware Security Module) 내부에 보관하고, 절대 외부에 노출하지 않으면서 서명만 수행해준다. IAM 정책으로 접근을 제어할 수 있고, CloudTrail로 모든 서명 요청이 기록된다.

필요한 IAM 권한은 딱 두 가지다:

1
2
3
4
5
6


{
 "Action": [
 "kms:Sign",
 "kms:GetPublicKey"
 ]
}

처음에는 “서명만 하면 되는데 왜 GetPublicKey까지 필요하지?“라는 의문이 들었다. 이 글은 그 의문을 따라가며 Ethereum 서명의 내부 구조를 파헤친 기록이다.

이 글에서 분석하는 코드는 go-ethereum-aws-kms-tx-signer 저장소를 기반으로 한다.

공개키 디코딩: KMS 응답에서 Ethereum 주소까지

KMS가 반환하는 공개키 포맷

AWS KMS의 GetPublicKey API는 DER-encoded X.509 SubjectPublicKeyInfo(RFC 5280) 형식으로 공개키를 반환한다.

1
2
3
4


SubjectPublicKeyInfo ::= SEQUENCE {
 algorithm AlgorithmIdentifier -- "EC 알고리즘, secp256k1 커브"
 subjectPublicKey BIT STRING -- 실제 공개키 바이트
}

왜 이런 포맷인가? KMS는 Ethereum 전용이 아니라 TLS 인증서, JWT 서명, 코드 서명 등 범용 암호화 서비스다. raw 공개키만 반환하면 받는 쪽에서 “이게 RSA인지 EC인지, 어떤 커브인지” 알 수 없다. SubjectPublicKeyInfo에 알고리즘과 커브 OID를 함께 담아 자기 설명적(self-describing) 포맷으로 만든 것이다.

참고로 KMS에 키를 import할 때는 PKCS#8(RFC 5958)을 사용한다:

방향	Import (키 넣을 때)	Export (GetPublicKey 응답)
대상	개인키 (private key)	공개키 (public key)
포맷	PKCS#8 (RFC 5958)	SubjectPublicKeyInfo (RFC 5280)

둘 다 AlgorithmIdentifier를 공유하는 X.509 계열 표준이며, 안에 담기는 게 개인키냐 공개키냐만 다르다.

ASN.1 파싱으로 공개키 바이트 추출

Go에서는 asn1.Unmarshal로 DER 껍질을 벗긴다. 실제 코드에서 ASN.1 구조체 정의를 보면:

1
2
3
4
5
6
7
8
9


type asn1EcPublicKey struct {
 EcPublicKeyInfo asn1EcPublicKeyInfo
 PublicKey asn1.BitString // ← 이것이 실제 공개키
}

type asn1EcPublicKeyInfo struct {
 Algorithm asn1.ObjectIdentifier // OID 1.2.840.10045.2.1 (EC)
 Parameters asn1.ObjectIdentifier // OID 1.3.132.0.10 (secp256k1)
}

KMS 응답에서 실제 공개키를 추출하는 getPublicKeyDerBytesFromKMS 함수:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func getPublicKeyDerBytesFromKMS(ctx context.Context, svc *kms.Client, keyId string) ([]byte, error) {
 getPubKeyOutput, err := svc.GetPublicKey(ctx, &kms.GetPublicKeyInput{
 KeyId: aws.String(keyId),
 })
 if err != nil {
 return nil, errors.Wrapf(err, "can not get public key from KMS for KeyId=%s", keyId)
 }

 // ASN.1 DER 파싱: SubjectPublicKeyInfo에서 공개키 바이트만 추출
 var asn1pubk asn1EcPublicKey
 _, err = asn1.Unmarshal(getPubKeyOutput.PublicKey, &asn1pubk)
 if err != nil {
 return nil, errors.Wrapf(err, "can not parse asn1 public key for KeyId=%s", keyId)
 }

 return asn1pubk.PublicKey.Bytes, nil
}

추출된 PublicKey.Bytes는 65바이트의 비압축(uncompressed) 공개키다:

1

[0x04] [---- X 좌표 32 bytes ----] [---- Y 좌표 32 bytes ----]

0x04는 RFC 5480 Section 2.2에서 정의한 “uncompressed point” 표시자다.

secp256k1 타원곡선의 기초

X, Y는 secp256k1 타원곡선 위의 좌표다.

$$y^2 = x^3 + ax + b \pmod{p}$$

secp256k1의 파라미터(모두 고정 상수):

$a = 0$, $b = 7$ → 즉, $y^2 = x^3 + 7 \pmod{p}$
$p = 2^{256} - 2^{32} - 977$
$G$ (generator point): 고정된 기준점
$n$ (order): $G$를 $n$번 점 덧셈하면 무한원점(항등원)으로 돌아감

$a$, $b$, $p$, $G$, $n$은 secp256k1 스펙에 고정된 상수이며 모든 사용자(Bitcoin, Ethereum 등)가 동일하다. 개인별로 달라지는 것은 **개인키 $k$**와 그로부터 파생되는 공개키 좌표 $(X, Y)$ 뿐이다.

공개키는 $(X, Y) = k \times G$로 계산된다. 여기서 $\times$는 일반 곱셈이 아니라 타원곡선 점 스칼라 곱셈(point scalar multiplication) — $G$를 $k$번 점 덧셈(point addition)하는 연산이다.

1
2


순방향: k → (X, Y) 계산 가능 (point multiplication)
역방향: (X, Y) → k 계산 불가능 (이산 로그 문제, ECDLP)

이것이 공개키 암호의 기반이며, KMS가 개인키 $k$를 외부에 노출하지 않고 서명만 수행하는 이유다.

공개키에서 Ethereum 주소 도출

Mastering Ethereum Ch.4에 따르면:

“The address is the last 20 bytes of the keccak256 hash of the public key”

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 1. 0x04 prefix 제거
rawPubKey := pubKeyBytes[1:] // 64 bytes (X || Y)

// 2. keccak256 해시 (Ethereum은 NIST SHA-3가 아닌 원본 Keccak-256 사용)
hash := sha3.NewLegacyKeccak256()
hash.Write(rawPubKey)
fullHash := hash.Sum(nil) // 32 bytes

// 3. 마지막 20 bytes = Ethereum 주소
address := fullHash[12:] // 20 bytes

왜 keccak256인가? Ethereum 개발 당시(2014~2015) NIST가 Keccak을 SHA-3(FIPS 202)로 표준화하면서 패딩을 변경했는데, Ethereum은 표준화 이전의 원본 Keccak을 이미 채택한 상태였다.

왜 앞 12바이트를 버리는가? 특별한 암호학적 이유는 없다. Bitcoin 주소도 20바이트이고, Ethereum이 이를 따른 것으로 보인다.

서명 과정: KMS Sign → Ethereum 서명 (r, s, v)

AWS KMS의 서명을 Ethereum이 요구하는 형식으로 변환하는 과정은 4단계로 나뉜다.

Step 1. 트랜잭션 해시를 KMS에 보내 서명 요청

1
2
3
4
5
6
7
8


txHashBytes := signer.Hash(tx).Bytes() // keccak256(RLP(tx))

signInput := &kms.SignInput{
 KeyId: aws.String(keyId),
 Message: txHashBytes,
 SigningAlgorithm: "ECDSA_SHA_256",
 MessageType: "DIGEST", // ← 반드시 지정!
}

MessageType: "DIGEST"를 반드시 지정해야 한다. 지정하지 않으면 KMS가 메시지를 한 번 더 해싱하여 잘못된 서명이 생성된다.

KMS 내부에서 일어나는 ECDSA 서명 알고리즘:

서명용 랜덤 nonce $k_{sig}$ 생성 (개인키 $k$와 다른 값, 서명마다 새로 생성)
$R = k_{sig} \times G$ (커브 위의 점)
$r = R_x \mod n$ (점 $R$의 x좌표)
$s = k_{sig}^{-1} \times (txHash + r \times privateKey) \mod n$

$s$ 수식에서 privateKey가 직접 사용된다. 이것이 “이 서명은 개인키 소유자만 만들 수 있다"는 것을 보장한다. 동시에 $s$에서 개인키를 역산하는 것은 이산 로그 문제(ECDLP)로 불가능하다.

Step 2. DER-encoded 서명을 파싱하여 r, s 추출

KMS는 ANS X9.62에 정의된 DER 형식으로 서명을 반환한다:

1
2
3
4


ECDSA-Sig-Value ::= SEQUENCE {
 r INTEGER, -- 점 R의 x좌표
 s INTEGER -- k_sig⁻¹ × (txHash + r × privateKey) mod n
}

getSignatureFromKms 함수에서 ASN.1 파싱:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


func getSignatureFromKms(
 ctx context.Context, svc *kms.Client, keyId string, txHashBytes []byte,
) ([]byte, []byte, error) {
 signInput := &kms.SignInput{
 KeyId: aws.String(keyId),
 SigningAlgorithm: awsKmsSignOperationSigningAlgorithm,
 MessageType: awsKmsSignOperationMessageType,
 Message: txHashBytes,
 }

 signOutput, err := svc.Sign(ctx, signInput)
 if err != nil {
 return nil, nil, err
 }

 // DER-encoded 서명을 ASN.1 파싱하여 r, s 정수값 추출
 var sigAsn1 asn1EcSig
 _, err = asn1.Unmarshal(signOutput.Signature, &sigAsn1)
 if err != nil {
 return nil, nil, err
 }

 return sigAsn1.R.Bytes, sigAsn1.S.Bytes, nil
}

Step 3. s 값 조정 — EIP-2와 “The Dark Side of the Curve”

타원곡선이 x축 대칭이므로, ECDSA에서는 $(r, s)$와 $(r, n-s)$ 둘 다 유효한 서명이다. 이는 트랜잭션 가변성(transaction malleability) 문제를 일으킨다 — 누군가 서명된 트랜잭션의 $s$를 $n-s$로 바꿔도 여전히 유효한 서명이 되어, 트랜잭션 해시가 바뀌고 추적이 어려워진다.

EIP-2는 이를 해결하기 위해 $s > secp256k1n/2$ 인 서명을 거부한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// secp256k1 커브의 order (n)
var secp256k1N = crypto.S256().Params().N

// EIP-2 기준값: n / 2
var secp256k1HalfN = new(big.Int).Div(secp256k1N, big.NewInt(2))

// s > n/2 이면 "dark side"에 있는 s를 "bright side"로 뒤집기
sBigInt := new(big.Int).SetBytes(sBytes)
if sBigInt.Cmp(secp256k1HalfN) > 0 {
 sBytes = new(big.Int).Sub(secp256k1N, sBigInt).Bytes()
}

“Dark side"라는 표현은 Lucas Henning의 글에서 유래한 것이다. EIP-2에서는 공식적으로 “non-canonical s value"라고 부른다.

모든 유효한 ECDSA 서명이 유효한 Ethereum 서명은 아니다!

go-ethereum 내부에서 실제로 체크하는 코드:

1
2
3
4
5
6
7
8


// github.com/ethereum/go-ethereum/crypto/crypto.go
func ValidateSignatureValues(v byte, r, s *big.Int, homestead bool) bool {
 // ...
 if homestead && s.Cmp(secp256k1halfN) > 0 {
 return false // ← s > N/2 이면 거부!
 }
 // ...
}

트랜잭션을 수신한 노드가 types.Sender() → recoverPlain() → ValidateSignatureValues()를 호출하여, $s > n/2$인 서명은 ErrInvalidSig로 거부한다.

Step 4. 올바른 v 값 찾기 (Recovery ID)

ECDSA 서명과 Ethereum 서명의 핵심 차이:

항목	ECDSA 표준 (RFC 3279)	Ethereum
형식	DER-encoded (r, s)	raw 65 bytes: `[r:32][s:32][v:1]`
r	점 R의 x좌표	동일
s	개인키·해시·r을 엮은 값, 0 < s < n 허용	동일하지만 s ≤ n/2 제약 (EIP-2)
v	없음	recovery id (0 또는 1)
용도	서명 유효성 검증	서명 + 공개키 복구 (발신자 주소 도출)

v가 필요한 이유: 타원곡선 $y^2 = x^3 + 7$에서 하나의 x값에 대해 y가 두 개 존재한다 ($y_1$, $y_2 = p - y_1$). 서명의 $r$은 점 $R$의 x좌표인데, 같은 x에 대해 $R = (x, y_1)$ 또는 $R = (x, y_2)$ 두 점이 가능하다.

1
2


v=0 → R = (x, y₁) 사용 → 공개키 A 복구
v=1 → R = (x, y₂) 사용 → 공개키 B 복구

$v$는 “$y_1$을 썼냐, $y_2$를 썼냐"를 알려주는 1비트 힌트다.

AWS KMS는 $v$를 반환하지 않으므로, 두 값을 모두 시도해서 원본 공개키와 일치하는 쪽을 찾는다. getEthereumSignature 함수가 바로 이 역할을 한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


func getEthereumSignature(expectedPublicKeyBytes []byte, txHash []byte, r []byte, s []byte) ([]byte, error) {
 rsSignature := append(adjustSignatureLength(r), adjustSignatureLength(s)...)

 // v=0 시도: R = (x, y₁) 가정
 signature := append(rsSignature, []byte{0}...)
 recoveredPublicKeyBytes, err := crypto.Ecrecover(txHash, signature)
 if err != nil {
 return nil, err
 }

 // 복구된 공개키와 원본 공개키 비교
 if hex.EncodeToString(recoveredPublicKeyBytes) != hex.EncodeToString(expectedPublicKeyBytes) {
 // v=1 시도: R = (x, y₂) 가정
 signature = append(rsSignature, []byte{1}...)
 recoveredPublicKeyBytes, err = crypto.Ecrecover(txHash, signature)
 if err != nil {
 return nil, err
 }

 if hex.EncodeToString(recoveredPublicKeyBytes) != hex.EncodeToString(expectedPublicKeyBytes) {
 return nil, errors.New("can not reconstruct public key from sig")
 }
 }

 return signature, nil // 65 bytes: [r:32][s:32][v:1]
}

expectedPublicKeyBytes가 바로 GetPubKey로 가져온 공개키다. 비교 대상 없이는 v=0이 맞는지 v=1이 맞는지 판단할 방법이 없다.

$v$는 고정값이 아니다. 같은 키라도 서명할 때마다 내부 nonce($k_{sig}$)가 달라지므로 v=0일 수도, v=1일 수도 있다.

Ethereum 트랜잭션에 from은 없다

이 사실이 GetPubKey가 필요한 근본적 이유와 연결된다.

RLP 인코딩에 from이 없는 이유

EIP-1559 (Type 2) 트랜잭션의 RLP 필드:

#	필드	설명
1	chainId	체인 ID
2	nonce	발신자의 트랜잭션 순번
3	maxPriorityFeePerGas	팁 상한
4	maxFeePerGas	가스 가격 상한
5	gasLimit	최대 가스 사용량
6	to	수신자 주소
7	value	전송 금액
8	data	호출 데이터
9	accessList	접근 목록
10	v	ECDSA recovery id
11	r	ECDSA 서명 r
12	s	ECDSA 서명 s

어떤 트랜잭션 타입이든 from 필드는 없다.

go-ethereum 코어 구조체

1
2
3
4
5
6
7
8
9


type Transaction struct {
 inner TxData // ← 합의(consensus) 데이터 (RLP로 인코딩되는 부분)
 time time.Time

 // caches (메모리에만 존재, 저장/전파 안 됨)
 hash atomic.Pointer[common.Hash]
 size atomic.Uint64
 from atomic.Pointer[sigCache] // ← 캐시! 블록에 저장되지 않음
}

from은 inner TxData(합의 데이터)가 아니라 caches 섹션에 있다. sigCache라는 이름 그대로, ecrecover 결과를 메모리에 캐싱해두는 필드일 뿐이다.

JSON-RPC 응답에 from이 보이는 이유

eth_getTransactionByHash나 eth_getTransactionReceipt 응답에 from이 포함되어 있지만, 이것은 노드가 응답을 만들 때 계산해서 넣어주는 것이다:

1
2
3
4
5


사용자 → eth_getTransactionByHash 요청
 → 노드가 DB에서 tx 조회 (from 없음)
 → 노드가 tx의 (v, r, s)에서 Sender() 호출 → from 계산
 → JSON 응답에 from 필드 추가
 → 사용자에게 반환

JSON-RPC 스펙의 from은 “API 응답에 이 필드를 포함해라"라는 인터페이스 규약이지, “이 데이터가 블록체인에 저장되어 있다"는 뜻이 아니다.

발신자 주소 복구 과정 (ecrecover)

1
2
3
4
5
6
7


트랜잭션 수신
 → types.Sender(signer, tx) 호출
 → recoverPlain(sighash, R, S, V)
 → crypto.Ecrecover(hash, sig) // sig = r || s || v, 65 bytes
 → secp256k1.RecoverPubkey(hash, sig) // v로 두 후보 중 하나 선택
 → 공개키 (65 bytes, 0x04 || X || Y)
 → keccak256(공개키[1:])[12:] = from 주소

go-ethereum 코어 레벨에서 $v$가 실제로 사용되며, $v$ 없이는 발신자를 알 수 없다.

전체 흐름: NewAwsKmsTransactorWithChainIDCtx

지금까지 설명한 모든 과정이 하나의 함수 NewAwsKmsTransactorWithChainIDCtx에 통합되어 있다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


func NewAwsKmsTransactorWithChainIDCtx(
 ctx context.Context, svc *kms.Client, keyId string, chainID *big.Int,
) (*bind.TransactOpts, error) {
 // [Step 1] KMS에서 공개키 가져오기 (kms:GetPublicKey 권한 필요)
 pubkey, err := GetPubKeyCtx(ctx, svc, keyId)
 if err != nil {
 return nil, err
 }

 // [Step 2] 공개키 → uncompressed 포맷 (65 bytes)
 pubKeyBytes := secp256k1.S256().Marshal(pubkey.X, pubkey.Y)

 // [Step 3] 공개키 → Ethereum 주소 도출
 keyAddr := crypto.PubkeyToAddress(*pubkey)
 if chainID == nil {
 return nil, bind.ErrNoChainID
 }

 signer := types.LatestSignerForChainID(chainID)

 // [Step 4] 트랜잭션 서명 함수 (signerFn)
 signerFn := func(address common.Address, tx *types.Transaction) (*types.Transaction, error) {
 if address != keyAddr {
 return nil, bind.ErrNotAuthorized
 }

 // (a) 트랜잭션 해시
 txHashBytes := signer.Hash(tx).Bytes()

 // (b) KMS 서명 → (r, s) 추출
 rBytes, sBytes, err := getSignatureFromKms(ctx, svc, keyId, txHashBytes)
 if err != nil {
 return nil, err
 }

 // (c) EIP-2: s > n/2 이면 뒤집기
 sBigInt := new(big.Int).SetBytes(sBytes)
 if sBigInt.Cmp(secp256k1HalfN) > 0 {
 sBytes = new(big.Int).Sub(secp256k1N, sBigInt).Bytes()
 }

 // (d) v 값 결정 + 최종 서명 조립
 signature, err := getEthereumSignature(pubKeyBytes, txHashBytes, rBytes, sBytes)
 if err != nil {
 return nil, err
 }

 // (e) 서명을 트랜잭션에 부착
 return tx.WithSignature(signer, signature)
 }

 return &bind.TransactOpts{
 From: keyAddr,
 Signer: signerFn,
 }, nil
}

공개키는 GetPubKeyCtx 내부에서 keyId 기준으로 캐싱되므로, 이후 서명 시에는 KMS API를 재호출하지 않는다:

1
2
3
4


type pubKeyCache struct {
 pubKeys map[string]*ecdsa.PublicKey
 mutex sync.RWMutex
}

결론: GetPubKey가 필요한 이유

모든 것을 종합하면:

단계	필요한 권한	이유
1. Ethereum 주소 결정	`kms:GetPublicKey`	공개키 → keccak256 → 주소
2. KMS 서명	`kms:Sign`	(r, s)만 반환, v 없음
3. v 값 결정	`kms:GetPublicKey` (캐시)	v=0, v=1로 ecrecover → 원본 공개키와 비교
4. 트랜잭션 전송	-	노드가 (v, r, s)에서 from 복구하여 검증

1
2
3
4
5
6


KMS 사용 흐름:
 GetPubKey → 공개키 → Ethereum 주소 (from)
 Sign(txHash) → (r, s) ← v가 없음!
 v 결정: ecrecover(txHash, r, s, v=0) == 공개키? → v=0, 아니면 v=1
 (v, r, s) 완성 → 트랜잭션 전송
 노드: ecrecover(txHash, v, r, s) → from 복구 → 잔액 확인 → 실행

만약 GetPubKey가 없다면:

Ethereum 주소를 알 수 없고
v 값을 결정할 수 없어
유효한 Ethereum 서명을 만들 수 없다

kms:Sign과 kms:GetPublicKey, 두 권한 모두 필수다.

참고 자료

Prometheus Alert 내부 동작 원리: 소스 코드로 파헤치기

Fri, 27 Feb 2026 00:00:00 +0000

Prometheus 알림 시스템의 내부 동작을 소스 코드 레벨에서 분석한 글이다. Rule Manager가 규칙 파일을 로드하고, 각 그룹을 주기적으로 평가하며, 최종적으로 Alertmanager에 알림을 전송하기까지의 전체 흐름을 다룬다.

Alert의 3가지 상태

Prometheus 알림은 아래 3가지 상태를 전이하며 동작한다.

출처: CSDN - Prometheus 告警源码分析

상태	설명
Inactive	조건을 충족하지 않는 상태. 알림이 비활성.
Pending	조건을 충족했지만 `for` 기간을 아직 채우지 못한 상태.
Firing	조건을 충족한 상태가 `for` 기간 이상 지속되어 알림이 발송되는 상태.

전체 흐름을 요약하면 다음과 같다:

rules.Manager가 실행되면 rules/*.yaml 파일을 읽고 모든 rules.Group을 로드한다.
각 그룹에 1개의 고루틴을 할당하고, 그룹 내 모든 규칙을 주기적으로 실행한다.
각 규칙에 대해:
- AlertingRule인 경우 Eval을 수행하고, 조건이 충족되면 sendAlerts로 알림을 전송한다.
- RecordingRule인 경우 Eval을 수행하고 결과를 TSDB에 기록한다.

출처: CSDN - Prometheus 告警源码分析

1. Manager 구조체

Manager는 Recording Rule과 Alerting Rule을 총괄 관리하는 구조체다. 규칙 파일 검색, 규칙 로드, 실행, 알림 전송까지 모든 과정을 담당한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// https://github.com/prometheus/prometheus/blob/main/rules/manager.go

type Manager struct {
 opts *ManagerOptions
 groups map[string]*Group // 규칙 그룹
 mtx sync.RWMutex
 block chan struct{} // 스토리지가 준비될 때까지 실행을 차단
 done chan struct{}
 restored bool
 logger log.Logger
}

NewManager

Manager를 생성할 때 주요 구성 옵션은 다음과 같다:

Appendable: 알림 규칙을 충족하는 데이터를 임시 저장하는 역할
Queryable: Appendable에 저장된 데이터를 쿼리하는 역할
QueryFunc: Prometheus 데이터를 쿼리하는 함수
NotifyFunc: 알림 조건이 충족되면 Alertmanager로 알림을 전송하는 함수
ResendDelay: 알림을 전송한 후, 이 시간이 지나야 재전송됨

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// https://github.com/prometheus/prometheus/blob/main/cmd/prometheus/main.go#L672

ruleManager = rules.NewManager(&rules.ManagerOptions{
 Appendable: fanoutStorage,
 Queryable: localStorage,
 QueryFunc: rules.EngineQueryFunc(queryEngine, fanoutStorage),
 NotifyFunc: rules.SendAlerts(notifierManager, cfg.web.ExternalURL.String()),
 Context: ctxRule,
 ExternalURL: cfg.web.ExternalURL,
 Registerer: prometheus.DefaultRegisterer,
 Logger: log.With(logger, "component", "rule manager"),
 OutageTolerance: time.Duration(cfg.outageTolerance),
 ForGracePeriod: time.Duration(cfg.forGracePeriod),
 ResendDelay: time.Duration(cfg.resendDelay),
})

2. 규칙 파일 로드

프로그램이 시작되면 일련의 reloader가 생성된다. 그 중 하나가 규칙 파일을 읽고 Manager를 업데이트하는 역할이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// https://github.com/prometheus/prometheus/blob/main/cmd/prometheus/main.go#L814

reloaders := []reloader{
 {
 name: "rules",
 reloader: func(cfg *config.Config) error {
 if agentMode {
 return nil
 }

 var files []string
 for _, pat := range cfg.RuleFiles {
 fs, err := filepath.Glob(pat)
 if err != nil {
 return fmt.Errorf("error retrieving rule files for %s: %w", pat, err)
 }
 files = append(files, fs...)
 }
 return ruleManager.Update(
 time.Duration(cfg.GlobalConfig.EvaluationInterval),
 files,
 cfg.GlobalConfig.ExternalLabels,
 externalURL,
 nil,
 )
 },
 },
}

설정 파일의 rule_files 항목에 지정된 패턴을 스캔하여, 매칭되는 모든 규칙 파일을 찾은 뒤 Manager.Update()를 호출한다.

3. Update: 규칙 그룹 갱신

Update는 규칙 파일을 파싱하고, 기존 그룹과 비교하여 변경된 그룹만 재시작하는 핵심 메서드다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


// https://github.com/prometheus/prometheus/blob/main/rules/manager.go#L175

func (m *Manager) Update(interval time.Duration, files []string, externalLabels labels.Labels,
 externalURL string, groupEvalIterationFunc GroupEvalIterationFunc) error {
 m.mtx.Lock()
 defer m.mtx.Unlock()

 // 규칙 그룹 로드
 groups, errs := m.LoadGroups(interval, externalLabels, externalURL, groupEvalIterationFunc, files...)
 if errs != nil {
 for _, e := range errs {
 level.Error(m.logger).Log("msg", "loading groups failed", "err", e)
 }
 return errors.New("error loading rules, previous rule set restored")
 }
 m.restored = true

 var wg sync.WaitGroup
 for _, newg := range groups {
 // 이미 존재하는 동일한 그룹이 변경되지 않았으면 건너뜀
 gn := GroupKey(newg.file, newg.name)
 oldg, ok := m.groups[gn]
 delete(m.groups, gn)

 if ok && oldg.Equals(newg) {
 groups[gn] = oldg
 continue
 }

 // 변경된 그룹은 기존 것을 중지하고 새로 실행
 wg.Add(1)
 go func(newg *Group) {
 if ok {
 oldg.stop()
 newg.CopyState(oldg)
 }
 wg.Done()
 <-m.block // 스토리지가 준비될 때까지 대기
 newg.run(m.opts.Context) // 그룹 실행 시작
 }(newg)
 }

 // 더 이상 필요 없는 이전 그룹 정리
 wg.Add(len(m.groups))
 for n, oldg := range m.groups {
 go func(n string, g *Group) {
 g.markStale = true
 g.stop()
 // 관련 메트릭 정리 ...
 wg.Done()
 }(n, oldg)
 }

 wg.Wait()
 m.groups = groups
 return nil
}

핵심 포인트:

LoadGroups로 파일에서 규칙 그룹을 파싱한다.
기존 그룹과 비교하여 변경되지 않은 그룹은 그대로 유지한다.
변경된 그룹은 이전 것을 중지(stop)하고, 상태를 복사(CopyState)한 뒤 새로 실행한다.
<-m.block 채널을 통해 스토리지가 초기화될 때까지 실행을 차단한다. 규칙 평가 시 데이터를 쿼리해야 하는데, 데이터 소스가 아직 준비되지 않았을 수 있기 때문이다.

4. Group.run(): 주기적 규칙 실행

각 그룹은 독립적인 고루틴에서 run()을 실행한다. 알림은 기본적으로 그룹 단위로 동작한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


// https://github.com/prometheus/prometheus/blob/main/rules/group.go#L155

func (g *Group) run(ctx context.Context) {
 defer close(g.terminated)

 // 일관된 슬롯 간격을 위해 초기 대기
 evalTimestamp := g.EvalTimestamp(time.Now().UnixNano()).Add(g.interval)
 select {
 case <-time.After(time.Until(evalTimestamp)):
 case <-g.done:
 return
 }

 tick := time.NewTicker(g.interval)
 defer tick.Stop()

 // 첫 번째 평가 실행
 g.evalIterationFunc(ctx, g, evalTimestamp)

 // 복원이 필요한 경우 추가 평가 후 상태 복원
 if g.shouldRestore {
 select {
 case <-g.done:
 return
 case <-tick.C:
 missed := (time.Since(evalTimestamp) / g.interval) - 1
 evalTimestamp = evalTimestamp.Add((missed + 1) * g.interval)
 g.evalIterationFunc(ctx, g, evalTimestamp)
 }
 g.RestoreForState(time.Now())
 g.shouldRestore = false
 }

 // 타이머 루프: 주기적으로 규칙 평가 실행
 for {
 select {
 case <-g.done:
 return
 default:
 select {
 case <-g.done:
 return
 case <-tick.C:
 missed := (time.Since(evalTimestamp) / g.interval) - 1
 if missed > 0 {
 g.metrics.IterationsMissed.WithLabelValues(GroupKey(g.file, g.name)).Add(float64(missed))
 g.metrics.IterationsScheduled.WithLabelValues(GroupKey(g.file, g.name)).Add(float64(missed))
 }
 evalTimestamp = evalTimestamp.Add((missed + 1) * g.interval)
 g.evalIterationFunc(ctx, g, evalTimestamp)
 }
 }
 }
}

evalIterationFunc은 내부적으로 g.Eval()을 호출하고, 실행 시간과 메트릭을 기록한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// https://github.com/prometheus/prometheus/blob/main/rules/manager.go#L76

func DefaultEvalIterationFunc(ctx context.Context, g *Group, evalTimestamp time.Time) {
 g.metrics.IterationsScheduled.WithLabelValues(GroupKey(g.file, g.name)).Inc()

 start := time.Now()
 g.Eval(ctx, evalTimestamp)
 timeSinceStart := time.Since(start)

 g.metrics.IterationDuration.Observe(timeSinceStart.Seconds())
 g.setEvaluationTime(timeSinceStart)
 g.setLastEvaluation(start)
 g.setLastEvalTimestamp(evalTimestamp)
}

5. Group.Eval(): 규칙 평가 실행

그룹 내 모든 규칙을 순차적으로 평가한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


func (g *Group) Eval(ctx context.Context, ts time.Time) {
 var samplesTotal float64

 for i, rule := range g.rules {
 select {
 case <-g.done:
 return
 default:
 }

 func(i int, rule Rule) {
 // 트레이싱 시작 ...

 g.metrics.EvalTotal.WithLabelValues(GroupKey(g.File(), g.Name())).Inc()

 // 규칙 평가 실행
 vector, err := rule.Eval(ctx, ts, g.opts.QueryFunc, g.opts.ExternalURL, g.Limit())
 if err != nil {
 rule.SetHealth(HealthBad)
 rule.SetLastError(err)
 g.metrics.EvalFailures.WithLabelValues(GroupKey(g.File(), g.Name())).Inc()
 return
 }
 rule.SetHealth(HealthGood)
 rule.SetLastError(nil)

 // AlertingRule이면 알림 전송
 if ar, ok := rule.(*AlertingRule); ok {
 ar.sendAlerts(ctx, ts, g.opts.ResendDelay, g.interval, g.opts.NotifyFunc)
 }

 // 결과를 TSDB에 기록
 app := g.opts.Appendable.Appender(ctx)
 for _, s := range vector {
 if s.H != nil {
 _, err = app.AppendHistogram(0, s.Metric, s.T, nil, s.H)
 } else {
 _, err = app.Append(0, s.Metric, s.T, s.F)
 }
 // 에러 처리 (OutOfOrder, TooOld, Duplicate 등) ...
 }
 app.Commit()
 }(i, rule)
 }
 g.cleanupStaleSeries(ctx, ts)
}

핵심 흐름:

그룹 내 규칙을 하나씩 꺼내 rule.Eval()을 실행한다.
AlertingRule이면 sendAlerts()를 호출하여 알림 전송을 시도한다.
평가 결과를 TSDB에 기록한다.

6. AlertingRule: 알림의 핵심

AlertingRule 구조체

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


type AlertingRule struct {
 name string
 vector parser.Expr // 알림 조건 PromQL 표현식
 holdDuration time.Duration // for 기간
 keepFiringFor time.Duration // 해소 후에도 유지할 시간
 labels labels.Labels
 annotations labels.Labels
 active map[uint64]*Alert // 현재 활성 알림 (Pending 또는 Firing)
 // ...
}

active 맵이 핵심이다. 레이블셋의 fingerprint를 키로 사용하여 현재 활성화된 알림 목록을 관리한다.

AlertingRule.Eval(): 상태 전이 로직

이 함수가 Prometheus Alert의 상태 전이 로직의 핵심이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


func (r *AlertingRule) Eval(ctx context.Context, ts time.Time, query QueryFunc,
 externalURL *url.URL, limit int) (promql.Vector, error) {

 // PromQL 쿼리 실행
 res, err := query(ctx, r.vector.String(), ts)
 if err != nil {
 return nil, err
 }

 resultFPs := map[uint64]struct{}{}
 alerts := make(map[uint64]*Alert, len(res))

 for _, smpl := range res {
 // 레이블 기반으로 해시값 생성
 lbs := lb.Labels()
 h := lbs.Hash()
 resultFPs[h] = struct{}{}

 alerts[h] = &Alert{
 Labels: lbs,
 ActiveAt: ts,
 State: StatePending,
 Value: smpl.F,
 }
 }

 r.activeMtx.Lock()
 defer r.activeMtx.Unlock()

 // 이미 활성 상태인 알림은 값만 업데이트
 for h, a := range alerts {
 if alert, ok := r.active[h]; ok && alert.State != StateInactive {
 alert.Value = a.Value
 alert.Annotations = a.Annotations
 continue
 }
 r.active[h] = a
 }

 // 상태 전이 판단
 for fp, a := range r.active {
 if _, ok := resultFPs[fp]; !ok {
 // 이번 평가에서 조건을 충족하지 않는 경우
 if a.State == StatePending ||
 (!a.ResolvedAt.IsZero() && ts.Sub(a.ResolvedAt) > resolvedRetention) {
 delete(r.active, fp) // 활성 목록에서 제거
 }
 if a.State != StateInactive {
 a.State = StateInactive
 a.ResolvedAt = ts
 }
 continue
 }

 // 이번 평가에서도 조건을 충족하는 경우
 if a.State == StatePending && ts.Sub(a.ActiveAt) >= r.holdDuration {
 a.State = StateFiring // Pending → Firing 전이
 a.FiredAt = ts
 }
 }

 return vec, nil
}

여기서 resolvedRetention은 하드코딩된 상수로 15분이다:

1

const resolvedRetention = 15 * time.Minute

상태 전이 규칙 정리

구체적인 상태 전이 규칙은 다음과 같다:

1. 이전에 활성이었지만 이번 평가에서 조건을 충족하지 않는 경우

StatePending 상태이거나, 해소된 지 15분이 지났다면 → active 목록에서 삭제
StateInactive가 아닌 상태라면 → StateInactive로 변경

2. 이전에 활성이었고 이번 평가에서도 조건을 충족하는 경우

StatePending 상태에서 for 기간을 초과했다면 → StateFiring으로 변경

3. 새롭게 조건을 충족한 경우

StatePending으로 생성하여 active 목록에 추가

7. sendAlerts(): 실제 알림 전송

Eval()에서는 상태만 변경하고, 실제 알림 전송은 sendAlerts()에서 수행한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


func (r *AlertingRule) sendAlerts(ctx context.Context, ts time.Time,
 resendDelay, interval time.Duration, notifyFunc NotifyFunc) {
 alerts := []*Alert{}
 r.ForEachActiveAlert(func(alert *Alert) {
 if alert.needsSending(ts, resendDelay) {
 alert.LastSentAt = ts
 // Eval 또는 Alertmanager 전송 실패 2회를 허용
 delta := resendDelay
 if interval > resendDelay {
 delta = interval
 }
 alert.ValidUntil = ts.Add(4 * delta)
 anew := *alert
 anew.Labels = alert.Labels.Copy()
 alerts = append(alerts, &anew)
 }
 })
 notifyFunc(ctx, r.vector.String(), alerts...)
}

알림 전송 조건

needsSending의 로직을 정리하면:

StatePending 상태 → 알림을 전송하지 않는다.
알림이 해소(Resolved)된 경우 → 해소 알림을 전송하여 문제가 해결되었음을 알린다.
마지막 전송 이후 ResendDelay 이상 경과한 경우 → 알림을 재전송한다. 그렇지 않으면 전송하지 않는다.

ValidUntil은 4 * delta로 설정되는데, 이는 Eval 실패나 Alertmanager 전송 실패가 2회 연속 발생하더라도 알림이 유효하게 유지되도록 하기 위한 것이다.

전체 흐름 요약

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


main()
 └─ rules.NewManager()
 └─ reloader: Update()
 └─ LoadGroups() ← 규칙 파일 파싱
 └─ Group.run() ← 그룹별 고루틴 실행
 └─ tick loop
 └─ Group.Eval()
 └─ for each rule:
 ├─ AlertingRule.Eval() ← 상태 전이
 │ └─ query() → 결과 비교 → 상태 변경
 ├─ sendAlerts() ← 알림 전송
 │ └─ needsSending() → notifyFunc()
 └─ TSDB에 결과 기록

Prometheus의 알림 시스템은 규칙 로드 → 주기적 평가 → 상태 전이 → 알림 전송이라는 명확한 파이프라인으로 구성되어 있다. 특히 StatePending 상태를 두어 일시적인 조건 충족에 대한 불필요한 알림을 방지하고, resolvedRetention(15분)을 통해 해소된 알림의 상태를 일정 기간 유지하는 설계가 인상적이다.

Reference

Seal Protocol: Sui 위의 탈중앙화 비밀 관리(DSM) 프로토콜 분석

Fri, 27 Feb 2026 00:00:00 +0000

Seal은 Sui 블록체인의 접근 제어(Access Control) 기능을 활용하여 데이터를 안전하게 암호화·복호화하는 탈중앙화 키 관리 프로토콜이다. Walrus와 같은 분산 스토리지나 온체인/오프체인 스토리지에 저장된 민감한 데이터를 보호하기 위해 설계되었으며, 중앙화된 키 저장소 없이 **수학적 파생(Derivation)**과 Threshold Cryptography로 보안을 유지한다.

1. 핵심 아키텍처

Seal은 데이터를 지키는 것이 아니라, 데이터를 잠근 **열쇠(AES Key)**를 지키는 역할을 수행한다.

하이브리드 암호화 모델 (Envelope Encryption)

Seal은 대용량 데이터 처리를 위해 봉투 암호화(Envelope Encryption) 방식을 채택했다.

데이터 암호화: 빠르고 강력한 AES-256(대칭키) 알고리즘으로 실제 데이터를 암호화한다. 키는 매번 랜덤 생성된다.
키 암호화: 생성된 AES Key를 Seal 프로토콜(IBE)을 통해 암호화하여 데이터 옆에 붙여둔다.

비유하자면, Seal은 금고(데이터)를 직접 지키는 게 아니라 금고 열쇠(AES Key)를 지키는 경비원이다.

Stateless Key Server

Seal의 Key Server는 AWS KMS와 달리 사용자 키를 DB에 저장하지 않는다.

Master Key Only: 서버는 오직 자신의 Master Key Pair 하나만 관리한다.
Key Derivation: 복호화 요청이 오면 Master Key + User ID를 결합하여 사용자용 키를 **즉석에서 계산(Derive)**한다.

유저가 수백만 명으로 늘어나도 서버의 DB 용량은 증가하지 않으며, 해킹을 당해도 특정 유저의 키가 저장되어 있지 않아 상대적으로 안전하다.

2. 기술적 배경

IBE (Identity-Based Encryption)

기존 PKI(인증서 방식)와 달리, 사용자의 신원(ID String, 이메일 등) 그 자체를 Public Key로 사용하는 암호화 방식이다. 복잡한 인증서 발급·관리 절차가 필요 없으며, ID만 알면 누구나 데이터를 암호화해서 보낼 수 있다.

Threshold Cryptography

단일 서버 실패(SPOF)를 방지하기 위해 비밀을 $n$개의 조각(Share)으로 나눈다. $n$개의 서버 중 $t$개 이상이 살아있고 승인해야만 원본 키를 복구할 수 있다. 예를 들어, 3개 서버 중 2개 승인 시 복호화가 가능하다. 이를 통해 고가용성(Liveness)과 보안성(Privacy)을 동시에 보장한다.

3. 작동 플로우

모든 암호화 및 복호화 연산은 **Client-Side(사용자 환경)**에서 이루어진다.

1단계: 수집 (Collection)

사용자는 복호화를 위해 분산된 Key Server들에게 접근 권한을 증명한다.

Client → Server A: “나 권한 있어(Proof)” → 키 조각 A 획득
Client → Server B: “나 권한 있어(Proof)” → 키 조각 B 획득
Server C가 응답하지 않아도 Threshold가 충족되면 진행 가능

2단계: 재조립 (Reconstruction)

클라이언트는 로컬 메모리 상에서 수집한 조각들을 합친다.

라그랑주 보간법(Lagrange Interpolation) 등 수학 공식을 통해 [조각 A + 조각 B]를 결합하고, 그 결과로 데이터를 잠갔던 **원본 대칭키(AES Key)**가 복구된다.

3단계: 해제 (Decryption)

복구된 AES Key를 사용하여 암호화된 객체(Encrypted Object)를 풀고, 최종적으로 원본 데이터(Plaintext)를 획득한다.

4. AWS KMS vs Seal 비교

특징	AWS KMS (저장소 모델)	Seal (파생 모델)
키 관리 방식	Stateful — 키를 DB/HSM에 영구 저장	Stateless — 유저 키를 저장하지 않음
스토리지 부담	유저/앱이 늘어날수록 관리할 키 데이터 증가	유저가 늘어나도 Master Key 1개만 관리
보안 리스크	저장소가 털리면 저장된 모든 키 유출 위험	저장소를 털어도 유저 키 데이터가 없음
백업/복구	모든 개별 키(CMK, DEK)를 백업해야 함	Master Key 하나만 백업하면 모든 유저 키 복구 가능
작동 원리	Key Lookup (DB 조회)	Key Derivation (수학적 계산)

5. Seal 내부 구조: 두 가지 핵심 컴포넌트

Seal은 크게 두 가지 컴포넌트로 구성된다.

Access Policies (On-chain, Sui)

Move 패키지(PkgId)가 IBE identity의 subdomain [PkgId]*를 제어한다. 패키지가 Move 코드를 통해 누가 해당 identity subdomain의 키에 접근할 수 있는지를 정의한다.

Off-chain Key Servers

각 Key Server는 단일 IBE Master Secret Key를 보유한다. 사용자가 특정 identity에 대한 파생 키를 요청하면, 온체인 접근 정책이 승인한 경우에만 파생 키를 반환한다.

6. 코드 레벨 분석

Encryption 과정

사용자 측에서 Seal Client SDK를 통해 데이터를 암호화하는 과정이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const mysecret = "mysupersecret";
const encoder = new TextEncoder();
const mysecretBz = encoder.encode(mysecret);

const { encryptedObject, key } = await sealClient.encrypt({
 threshold: 1,
 packageId: PACKAGE_ID,
 id: "0000",
 data: mysecretBz,
});

encrypt 내부 로직

SDK 내부에서는 다음 과정을 거친다.

랜덤 Base Key 생성: encryptionInput.generateKey()로 AES-256 키를 랜덤 생성
키 분할: split(baseKey, threshold, keyServers.length)로 Shamir Secret Sharing 수행
Share 암호화: 각 Key Server의 Public Key로 개별 Share를 IBE 암호화
DEM Key 파생: Base Key + 암호화된 Share 정보로 실제 데이터 암호화용 키를 파생
데이터 암호화: 파생된 DEM Key로 원본 데이터를 AES-GCM 암호화
직렬화: 모든 메타데이터와 ciphertext를 BCS 포맷으로 직렬화하여 반환

1
2
3
4
5
6


// 핵심 흐름 요약
const baseKey = await encryptionInput.generateKey();
const shares = split(baseKey, threshold, keyServers.length);
const encryptedShares = encryptBatched(keyServers, kemType, fullId, shares, baseKey, threshold);
const demKey = deriveKey(KeyPurpose.DEM, baseKey, encryptedShares, threshold, serverIds);
const ciphertext = await encryptionInput.encrypt(demKey);

7. Limitations

seal_approve* 함수는 풀 노드에서 dry_run_transaction_block RPC 호출을 통해 평가된다. 풀 노드는 비동기적으로 동작하기 때문에 다음 사항에 유의해야 한다.

온체인 상태 변경이 전파되는 데 시간이 걸릴 수 있어, 풀 노드가 항상 최신 상태를 반영하지는 않는다.
seal_approve* 함수는 모든 Key Server에 걸쳐 원자적으로 평가되지 않는다. 자주 변경되는 상태에 의존하여 접근 권한을 결정하면 안 된다.
seal_approve* 함수는 side-effect가 없어야 하며, 온체인 상태를 수정할 수 없다.
Random 모듈은 사용 가능하지만, 풀 노드 간에 결정적이지 않으므로 seal_approve* 함수 내에서 사용하면 안 된다.

8. 결론

Seal은 메시지를 encrypt & decrypt 해주는 프로토콜이다. IBE(Identity-Based Encryption)에 기초해서 동작하며, 이 모델이 서비스되기 위해 필요한 핵심 컴포넌트는 Key Server다.

Key Server들은 Master Key를 보유하고, 클라이언트의 ID를 바탕으로 파생 키를 만든다(이 형태가 IBE). 다만 Seal에서는 실제 고용량 데이터를 직접 IBE로 암호화하지 않고, 매번 랜덤하게 새로운 AES Key를 생성한 뒤 이 키를 각 Key Server들이 나눠 갖는 형태(Envelope Encryption + Secret Sharing)로 운영된다.

Sui 블록체인을 접근 제어 레이어로, IBE와 Threshold Cryptography를 키 관리 레이어로 사용하는 Stateless 아키텍처를 통해 보안성과 확장성을 동시에 달성한 프로토콜이다.

References

EVM은 왜 정수(uint)만 지원하는가?

Wed, 25 Feb 2026 00:00:00 +0000

Solidity에 float이 없는 이유와 블록체인 합의의 관계

핵심 이유: 부동소수점은 합의를 깨뜨린다

블록체인은 수천 개 노드가 동일한 계산을 수행하고 같은 결과에 합의해야 하는 시스템이다.

그런데 IEEE 754 부동소수점(float/double)은 하드웨어마다 미세하게 다른 결과를 낼 수 있다:

1
2
3
4
5
6
7


0.1 + 0.2 =
 Node A (Intel x86): 0.30000000000000004
 Node B (ARM Cortex): 0.30000000000000001
 Node C (AMD Ryzen): 0.30000000000000004

→ A와 C는 같은 상태 해시, B는 다른 상태 해시
→ 합의 실패 → 체인 포크!

반면 정수 연산은 어떤 CPU에서든 동일하다:

1
2


800 * 1e18 / 1000 = 800000000000000000
→ 100% 결정론적(deterministic) → 합의 보장

이유 1: 결정론(Determinism) — 가장 근본적

float이 비결정론적인 구체적 원인들을 살펴보자.

반올림 모드 차이

IEEE 754에는 4가지 반올림 모드가 있다:

Round to nearest (even) — 기본값이지만 바꿀 수 있음
Round toward zero
Round toward +∞
Round toward -∞

CPU나 컴파일러 설정에 따라 모드가 달라질 수 있다.

비결합법칙 (Non-associativity)

1
2


정수: (a + b) + c = a + (b + c) ← 항상 같음
float: (a + b) + c ≠ a + (b + c) ← 다를 수 있음!

예를 들어 a=1e20, b=-1e20, c=1.0일 때:

1
2


(a + b) + c = 0 + 1.0 = 1.0
a + (b + c) = 1e20 + (-1e20) = 0.0

컴파일러 최적화가 연산 순서를 바꾸면 결과가 달라진다.

특수값 처리 차이

NaN, Infinity, -0, denormalized numbers 등 특수값들의 비교·연산 동작이 구현마다 미세하게 다르다.

이유 2: 금융 정밀도 — float은 돈 계산에 위험

은행도 float을 쓰지 않는다:

시스템	방식
COBOL	고정소수점 (packed decimal)
Java	`BigDecimal`
Python	`decimal` 모듈
블록체인	`uint256` + 1e18 스케일링

float의 위험을 구체적으로 보면:

1
2
3
4


잔고 100.10 USDC를 float로 저장하면?
→ 실제 저장값: 100.09999999999999...
→ 100만 번 더하기/빼기 반복하면 오차 누적
→ 잔고 불일치 → 자금 손실 또는 무한 인출 취약점

uint256 + PRECISION 방식:

1
2


100.10 USDC = 100_100_000 (USDC는 6 decimals)
→ 정확히 이 값. 오차 없음. 1000만 번 연산해도 동일.

이유 3: EVM 설계 단순화

EVM은 256비트 워드 기반 스택 머신이다. uint256 하나로 통일하면:

장점
Opcode 수 적음 (`ADD`, `MUL`, `DIV`)
가스 비용 계산 간단 (고정 비용)
구현 버그 감소
상태 저장 단순 (32 bytes 슬롯)

만약 float을 추가한다면:

추가 복잡도
`FADD`, `FMUL`, `FDIV`, `FSQRT` opcode
반올림 모드 명세
`NaN`, `Infinity`, `-0` 처리 규칙
가스 비용 산정 (연산마다 다름)
`int↔float` 변환 opcode
모든 EVM 구현체의 동작 일치 검증

복잡도 대비 이점이 없다. 정수 스케일링으로 충분하기 때문이다.

다른 블록체인도 마찬가지인가?

L2도 float을 명시적으로 제거한다:

Optimism (Bedrock): float 연산 제외 — fraud proof 검증을 위해
Arbitrum Nitro: float 연산 제외 — 동일한 이유

다른 체인들도 마찬가지다:

체인	방식
Solana (BPF)	정수 연산만 지원, float는 프로그램 레벨에서 처리
Cosmos (CosmWasm)	`Decimal256` 타입 제공 (uint 기반 구현)
Move (Sui/Aptos)	`u8`/`u64`/`u128`/`u256`만 지원, float 없음

블록체인 VM에서 float 배제는 업계 표준이다.

DeFi의 우회 방법들

float 없이 소수점을 다루는 방법들:

방식	사용 사례
1e18 (Mantissa)	Compound — 범용 비율 계산
1e27 (Ray)	Aave V3 — 더 높은 정밀도 필요 시
2^96 (Q notation)	Uniswap V3 — 제곱근 가격 계산 최적화
Token decimals	USDC(6), WETH(18) — 토큰 단위 표현
WAD/RAY 라이브러리	ds-math, WadRayMath — 안전한 연산

공통 패턴: “정수로 표현하고, 나눗셈은 최대한 늦추고, 곱셈을 먼저”

결론

EVM이 uint만 지원하는 이유를 우선순위로 정리하면:

합의 안전성 — float은 노드 간 결과 차이를 만들 수 있음
금융 정확성 — 돈 계산에 부동소수점은 위험
설계 단순성 — opcode와 가스 모델 복잡도 최소화

이것은 **“기술적 한계"가 아니라 “의도적 설계 결정”**이다.

분산 합의가 필요 없는 시스템(게임 엔진, 과학 계산)에서는 float이 적합하지만, “수천 대 컴퓨터가 같은 답을 내야 하는” 블록체인에서는 정수가 유일한 선택이다.

Lending Protocol Study Day 2: Compound V2 Deep Dive와 Aave V3 아키텍처

Wed, 25 Feb 2026 00:00:00 +0000

7일간의 DeFi Lending Protocol 스터디 시리즈. Day 2에서는 Compound V2의 내부 구조를 코드 레벨로 파고들고, 렌딩 프로토콜의 3가지 유형을 분류한 뒤, Aave V3의 아키텍처 진화를 분석한다.

Repository: jeongseup/lending-protocol-study

Day 2 목표

Compound V2의 CToken 상속 구조와 “Fresh” 패턴을 코드 레벨로 이해한다
Mantissa 기반 고정소수점 연산과 Lazy Interest Accrual 메커니즘을 파악한다
렌딩 프로토콜을 3가지 유형(Pool-based, CDP-based, Fixed-rate)으로 분류한다
Aave V3의 비트맵 스토리지 최적화와 아키텍처 진화를 분석한다

Compound V2 Deep Dive: CToken 상속 구조

Day 1에서 Compound V2의 핵심 파일 3개를 언급했다. Day 2에서는 CToken의 상속 구조부터 파고든다.

1
2
3
4


CTokenInterface (인터페이스)
 └─ CToken (핵심 로직)
 ├─ CErc20 (ERC20 자산용 - USDC, DAI 등)
 └─ CEther (ETH 전용)

CErc20과 CEther의 차이는 단순하다. ETH는 ERC20이 아니라 msg.value로 받아야 하므로, 자금 수수 로직만 다르고 핵심 렌딩 로직은 CToken에 모두 있다.

중요한 건 CToken이 풀 역할까지 겸한다는 점이다. mint(), borrow(), repay(), liquidate() 모두 CToken 컨트랙트에 있다. 하나의 컨트랙트가 ERC20 토큰이면서 동시에 렌딩 풀인 Monolithic 구조다.

Fresh 패턴: “이자부터 정산하고 본론으로”

Compound V2의 모든 핵심 함수 이름에 Fresh가 붙어 있다.

1
2
3
4


function mintFresh(address minter, uint mintAmount) internal
function borrowFresh(address payable borrower, uint borrowAmount) internal
function repayBorrowFresh(address payer, address borrower, uint repayAmount) internal
function liquidateBorrowFresh(address liquidator, address borrower, ...) internal

왜 Fresh일까? **“이자를 최신 상태로 정산한 뒤에 핵심 로직을 실행한다”**는 패턴이다.

1
2
3
4


function mint(uint mintAmount) external returns (uint) {
 accrueInterest(); // 1. 이자 먼저 정산
 return mintFresh(msg.sender, mintAmount); // 2. 그 다음 본론
}

모든 external 함수가 이 패턴을 따른다:

1

사용자 호출 → accrueInterest() → xxxFresh() → 실제 로직

이렇게 하는 이유는 간단하다. 이자 계산은 마지막 업데이트 이후의 블록 수에 기반한다. 이자를 정산하지 않고 mint()을 실행하면, 기존 예치자들의 교환비율이 부정확한 상태에서 새로운 지분이 발행되어 기존 예치자가 손해를 본다.

Mantissa: Solidity의 소수점 해법

Solidity에는 부동소수점이 없다. Compound V2는 이를 Mantissa 방식으로 해결한다.

$$\text{Mantissa} = \text{실제값} \times 10^{18}$$

예를 들어:

이자율 5% → 0.05 × 10^18 = 50000000000000000
교환비율 0.02 → 0.02 × 10^18 = 20000000000000000

곱셈과 나눗셈 시 스케일링을 맞춰야 한다:

1
2
3
4
5
6
7
8


// 두 Mantissa 값의 곱셈: 결과를 10^18으로 나눠서 스케일 복원
function mulScalar(Exp memory a, uint scalar) pure internal returns (Exp memory) {
 return Exp({mantissa: a.mantissa * scalar});
}

function mulExp(Exp memory a, Exp memory b) pure internal returns (Exp memory) {
 return Exp({mantissa: a.mantissa * b.mantissa / 1e18});
}

이 패턴은 Compound만의 것이 아니다. Aave의 RAY(10^27), Uniswap V3의 Q96(2^96), MakerDAO의 WAD(10^18) 모두 같은 원리다. 정수로 소수점을 표현하기 위한 고정소수점 연산.

Lazy Interest Accrual: 이자는 “필요할 때만” 계산한다

accrueInterest()는 매 블록마다 자동으로 실행되는 게 아니다. 누군가 트랜잭션을 보낼 때만 실행된다. 이것이 Lazy Evaluation이다.

1
2
3


블록 100: Alice가 mint() → accrueInterest() 실행 (블록 0~100 이자 계산)
블록 200: 아무 일 없음 → 이자 계산 안 함
블록 300: Bob이 borrow() → accrueInterest() 실행 (블록 100~300 이자 계산)

200 블록 동안 아무도 상호작용하지 않으면, 200 블록치의 이자가 한번에 계산된다. 가스비는 트랜잭션 수가 아니라 상호작용 빈도에 비례한다.

accrueInterest()가 업데이트하는 상태 변수는 딱 4개다:

1
2
3
4


totalBorrows // 총 대출량 (이자 포함)
totalReserves // 프로토콜 수익 누적
borrowIndex // 대출자 이자 추적용 전역 인덱스
accrualBlockNumber // 마지막 이자 정산 블록 번호

4개의 SSTORE = 20,000 gas. 사용자 수가 아무리 많아도 이 비용은 고정이다. 이것이 Day 1에서 설명한 Scaled Balance 패턴의 실제 구현이다.

이자 시나리오 시뮬레이션

구체적인 숫자로 따라가보자.

초기 상태

1
2
3
4
5
6


블록 0: Pool에 10,000 USDC
- totalCash = 10,000
- totalBorrows = 0
- totalReserves = 0
- borrowIndex = 1.0 (1e18)
- exchangeRate = 10,000 / 500,000 = 0.02 (cToken 500,000개 발행 가정)

Alice가 1,000 USDC 대출

1
2
3
4
5


블록 100: Alice borrow(1,000)
- accrueInterest() 실행 (totalBorrows = 0이므로 이자 없음)
- totalCash = 9,000 (1,000 빠짐)
- totalBorrows = 1,000
- Alice의 borrowSnapshot = {principal: 1,000, interestIndex: 1.0}

100블록 후 이자 정산

1
2
3
4
5
6
7


블록 200: Bob이 mint() 호출
- 이자율: borrowRate = 0.0001/블록 (연 약 5.3%)
- 경과 블록: 100
- simpleInterestFactor = 0.0001 × 100 = 0.01
- 새 totalBorrows = 1,000 × 1.01 = 1,010
- Reserve Factor 10%: 새 totalReserves = 10 × 0.1 = 1
- 새 borrowIndex = 1.0 × 1.01 = 1.01

Alice의 실제 대출 잔액은?

$$\text{Alice 대출잔액} = \frac{\text{principal} \times \text{현재 borrowIndex}}{\text{Alice의 interestIndex}} = \frac{1{,}000 \times 1.01}{1.0} = 1{,}010 \text{ USDC}$$

Alice의 Storage를 건드리지 않고도 전역 borrowIndex 하나만으로 정확한 잔액을 계산했다.

렌딩 프로토콜의 3가지 유형

Day 1에서는 Pool-based 모델만 다뤘다. 실제로 렌딩 프로토콜은 자금 조달 방식에 따라 3가지로 분류된다.

1. Pool-based (Compound, Aave)

1

예치자 → [Pool] → 차입자

기존 예치금에서 대출
예치자가 없으면 빌릴 수 없다
이자율은 Utilization Rate에 연동

2. CDP-based (MakerDAO)

1

사용자 → [Vault] → 새 DAI 발행

프로토콜이 새 토큰을 발행 (mint)
예치자 없이도 대출 가능
Stability Fee(이자)는 거버넌스가 결정
CDP = Collateralized Debt Position

3. Fixed-rate (Yield Protocol)

1

사용자 → fyToken (만기 시 1:1 교환 가능)

할인된 미래 가치 토큰 매매
0.95 fyUSDC를 사면, 만기에 1 USDC → 약 5% 고정 금리
이자율이 트레이딩으로 결정

비교 정리

특성	Pool-based	CDP-based	Fixed-rate
자금 출처	예치자	프로토콜 발행	시장 매매
이자율 결정	알고리즘 (사용률)	거버넌스 투표	시장 수급
변동/고정	변동	반고정	고정
대표	Compound, Aave	MakerDAO	Yield, Notional
필요 조건	유동성 공급자	없음 (mint)	만기 매칭

대부분의 메이저 프로토콜이 Pool-based인 이유: 구현이 단순하고, 유동성이 자연스럽게 형성되기 때문이다. CDP는 토큰 경제 설계가 복잡하고, Fixed-rate는 만기 매칭이 어렵다.

Aave V3 아키텍처: Compound에서 무엇이 진화했나

Compound V2는 CToken이 모든 걸 한다. Aave V3는 이를 분리했다.

1
2
3
4
5
6
7


Compound V2:
 사용자 → CToken.mint() (CToken = 풀 + 토큰)

Aave V3:
 사용자 → Pool.supply() (Pool = 라우터)
 → SupplyLogic.executeSupply() (Library = 실제 로직)
 → aToken.mint() (aToken = 순수 영수증)

delegatecall + Library 패턴

Aave V3의 Pool.sol은 얇은 프록시에 가깝다. 실제 로직은 Library 컨트랙트에 있다.

1
2
3
4
5
6
7
8


// Pool.sol
function supply(address asset, uint256 amount, ...) external {
 SupplyLogic.executeSupply(...); // delegatecall로 Library 호출
}

function borrow(address asset, uint256 amount, ...) external {
 BorrowLogic.executeBorrow(...);
}

Library를 쓰면:

코드 크기 제한(24KB) 회피 - Pool의 로직이 아무리 커도 Library에 분산
관심사 분리 - Supply, Borrow, Liquidation 로직이 독립적으로 관리
단, Library는 독립 배포 후 업그레이드 불가 - Proxy 패턴과 조합하여 해결

Debt Tokenization

Compound V2에서 대출은 단순 매핑이다:

1
2


// Compound V2
mapping(address => BorrowSnapshot) accountBorrows;

Aave V3는 대출도 토큰화했다:

1
2
3


// Aave V3
variableDebtToken.mint(borrower, amount); // 대출하면 부채 토큰 발행
variableDebtToken.burn(borrower, amount); // 상환하면 부채 토큰 소각

부채를 토큰화하면 무엇이 좋은가?

balanceOf()로 대출 잔액 조회 가능 (표준 인터페이스)
Transfer 제한으로 부채 이전 방지
이벤트 표준화 (Transfer 이벤트로 대출/상환 추적 가능)

Aave V3.2부터 Stable Rate이 제거되었다. 변동금리만 남았으므로 stableDebtToken은 더 이상 사용되지 않는다.

비트맵 스토리지 최적화

Day 2의 가장 중요한 기술적 발견이다. Compound V2와 Aave V3의 사용자 상태 관리 방식이 근본적으로 다르다.

Compound V2: 배열 순회

1
2
3
4
5
6
7


// Comptroller.sol
mapping(address => CToken[]) public accountAssets; // 사용자별 참여 마켓 배열

// Health Factor 계산 시
for (uint i = 0; i < assets.length; i++) {
 // 모든 마켓을 순회하며 담보 가치 합산
}

문제: 사용자가 참여한 마켓이 많을수록 가스비가 선형으로 증가한다.

Aave V3: 비트맵

1
2
3
4
5
6
7


// 하나의 uint256에 128개 자산의 상태를 담는다
// 각 자산이 2비트를 차지: [담보 사용 여부][대출 여부]
mapping(address => UserConfigurationMap) internal _usersConfig;

struct UserConfigurationMap {
 uint256 data; // 256비트 = 128개 자산 × 2비트
}

비트맵의 구조:

1
2
3
4
5


비트 위치: ... | 5 | 4 | 3 | 2 | 1 | 0 |
자산 ID: | 2 | 1 | 0 |
의미: ... | C | B | C | B | C | B |
 B = Borrowing (대출 중)
 C = Collateral (담보로 사용 중)

Health Factor 계산 시:

1
2
3
4


// 비트맵에서 해당 비트가 0이면 스킵
if (userConfig.data & (1 << (reserveIndex * 2)) == 0) {
 continue; // 이 자산은 대출도 담보도 아님 → O(1)로 스킵
}

성능 비교

1
2
3
4
5


Compound V2 (배열):
 10개 마켓 참여 → 10번 SLOAD + 루프 = ~50,000 gas

Aave V3 (비트맵):
 128개 마켓 확인 → 1번 SLOAD + 비트 연산 = ~2,100 gas

비트 연산(AND, SHIFT)은 3 gas다. 128개 자산을 확인해도 2,100 + 128 × 3 = 2,484 gas. 배열 방식 대비 약 20배 절약이다.

이 차이가 결정적인 이유: Health Factor 계산은 모든 트랜잭션에서 발생한다. supply, borrow, repay, liquidate 전부. 가장 빈번하게 호출되는 로직의 가스를 20배 줄이면 프로토콜 전체의 가스 효율이 극적으로 개선된다.

LendingPool 리팩토링: 배운 것을 적용하기

스터디 프로젝트의 LendingPool.sol에 Aave V3의 PoolStorage 패턴을 적용했다.

Before: 단순 매핑

1
2


mapping(address => mapping(address => uint256)) public deposits;
mapping(address => mapping(address => uint256)) public borrows;

After: 구조화된 스토리지

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


struct ReserveData {
 uint128 liquidityIndex;
 uint128 variableBorrowIndex;
 uint128 currentLiquidityRate;
 uint128 currentVariableBorrowRate;
 uint40 lastUpdateTimestamp;
 uint16 id;
 address aTokenAddress;
 address variableDebtTokenAddress;
 uint128 totalDeposits;
 uint128 totalBorrows;
}

mapping(address => ReserveData) internal _reserves;
mapping(uint256 => address) internal _reservesList;
uint16 internal _reservesCount;

mapping(address => UserConfigurationMap) internal _usersConfig;

핵심 변경점:

_reserves: 자산 주소 → ReserveData 매핑 (모든 자산 상태를 하나의 구조체로)
_reservesList: reserveId → 자산 주소 매핑 (비트맵 인덱싱용)
_usersConfig: 사용자별 비트맵 (담보/대출 상태)

비트맵 헬퍼도 구현했다:

1
2
3
4
5
6
7
8
9


function isUsingAsCollateral(UserConfigurationMap memory self, uint256 reserveIndex)
 internal pure returns (bool) {
 return (self.data >> (reserveIndex * 2 + 1)) & 1 != 0;
}

function isBorrowing(UserConfigurationMap memory self, uint256 reserveIndex)
 internal pure returns (bool) {
 return (self.data >> (reserveIndex * 2)) & 1 != 0;
}

리팩토링 후 모든 62개 테스트(기존 61 + 비트맵 테스트 1)가 통과했다.

JumpRateModel 테스트: Fuzz Testing까지

Day 1에서 이론으로 다룬 JumpRateModel을 실제로 구현하고 테스트했다.

Unit Test: 18개 케이스

1
2
3
4
5
6


[PASS] testGetBorrowRate_ZeroUtilization()
[PASS] testGetBorrowRate_AtKink()
[PASS] testGetBorrowRate_AboveKink()
[PASS] testGetBorrowRate_FullUtilization()
[PASS] testGetSupplyRate_WithReserveFactor()
... (18개 전부 통과)

Fuzz Test: 6개 케이스

1
2
3
4
5
6
7
8
9


function testFuzz_BorrowRateMonotonicity(uint256 util1, uint256 util2) public {
 util1 = bound(util1, 0, 1e18);
 util2 = bound(util2, util1, 1e18);

 uint256 rate1 = model.getBorrowRate(cash1, borrows1, reserves1);
 uint256 rate2 = model.getBorrowRate(cash2, borrows2, reserves2);

 assertGe(rate2, rate1); // 사용률이 높으면 이자율도 높아야 한다
}

Fuzz Testing으로 검증한 불변 조건:

단조 증가: 사용률이 올라가면 이자율도 올라간다
Supply ≤ Borrow: Supply Rate은 항상 Borrow Rate 이하
Kink에서의 연속성: kink 전후로 이자율이 비연속적으로 뛰지 않는다

전체 24개 테스트 (18 unit + 6 fuzz) 모두 통과.

Day 2 핵심 인사이트 정리

Fresh 패턴은 렌딩의 정합성을 보장한다 - 이자를 먼저 정산하지 않으면 교환비율이 부정확해져서 기존 사용자가 손해본다. “이자부터, 그 다음 본론"이 원칙.
Lazy Interest Accrual은 가스 효율의 핵심 - 매 블록이 아니라 트랜잭션이 발생할 때만 이자를 계산한다. 4개의 SSTORE로 전체 사용자의 이자를 한번에 정산.
렌딩은 3가지 유형 - Pool-based(예치금에서 빌림), CDP-based(새 토큰 발행), Fixed-rate(할인 토큰). 대부분이 Pool-based인 이유는 구현 단순성과 유동성 형성의 용이함.
비트맵이 아키텍처를 결정한다 - Compound의 배열 vs Aave의 비트맵. 한 번의 SLOAD로 128개 자산 상태를 확인하는 것은 단순한 최적화가 아니라, Health Factor 계산이 모든 트랜잭션에서 발생하기 때문에 프로토콜 전체 가스 효율을 좌우한다.
Storage 레이아웃이 아키텍처를 결정한다 - Compound는 배열 중심이라 Monolithic이 자연스럽고, Aave는 비트맵 + 구조체 중심이라 Modular가 자연스럽다. 데이터 구조가 코드 구조를 결정한다.

Next: Day 3

내일은 청산(Liquidation) 메커니즘을 파고든다.

청산 트리거 조건과 liquidateBorrowFresh() 코드 리딩
청산 보너스(Liquidation Incentive) 경제학
Foundry Fork Testing으로 Aave V3 메인넷 청산 시뮬레이션
고급 Foundry 테스팅 패턴 (invariant, fork)

이 시리즈의 전체 코드와 학습 자료는 lending-protocol-study 레포에서 확인할 수 있다.

Lending Protocol Study Day 1: DeFi 렌딩의 핵심 개념과 아키텍처

Mon, 23 Feb 2026 00:00:00 +0000

7일간의 DeFi Lending Protocol 스터디 시리즈. 백엔드/인프라 엔지니어 관점에서 렌딩 프로토콜을 코드 레벨까지 파헤친다.

Repository: jeongseup/lending-protocol-study

Why Lending Protocol?

블록체인 인프라 엔지니어로 일하면서 노드 운영, 밸리데이터 모니터링, 스테이킹 보상 분석 등을 해왔다. 그런데 DeFi의 가장 큰 축인 렌딩 프로토콜은 “대충 알겠는데 코드 레벨에서는 모른다"는 상태였다.

이번 스터디의 목표는 명확하다:

Compound V2 / Aave V3의 핵심 로직을 코드로 읽고 구현한다
렌딩의 수학적 모델(이자율, 청산, Health Factor)을 공식 수준으로 이해한다
Solidity + Go 모니터링 도구까지 만들어 실무에 적용 가능한 수준으로 올린다

렌딩 프로토콜의 본질: 풀 기반 중개

전통 금융의 대출은 대출자와 차입자를 1:1로 매칭한다. DeFi 렌딩은 다르다.

1
2


전통 금융: Alice → [은행] → Bob (1:1 매칭)
DeFi 렌딩: Alice → [Pool] ← Bob (풀 기반 간접 매칭)

예치자들이 자산을 풀에 넣으면, 차입자들이 담보를 걸고 풀에서 빌려간다. 아무도 누가 누구에게 빌려줬는지 모른다. 이자율은 풀의 사용률(Utilization Rate)에 따라 알고리즘이 자동으로 결정한다.

이 구조의 핵심 이유는 간단하다:

1

블록체인 = 익명 → 신용평가 불가 → 담보로만 판단 → 과담보 필수

신용이 없으니 담보로 대체한다. 그래서 DeFi 렌딩은 태생적으로 과담보(Over-collateralized) 구조다.

렌딩의 5대 핵심 파라미터

렌딩 프로토콜을 이해하려면 이 5가지 숫자만 확실히 알면 된다.

파라미터	의미	일반적 범위
LTV (Loan-to-Value)	담보 대비 얼마까지 빌릴 수 있나	75-80%
Health Factor	내 포지션이 안전한가 (< 1이면 청산)	1.0 이상 유지
Utilization Rate	풀의 자금 중 얼마가 빌려졌나	이자율 결정
Reserve Factor	프로토콜이 이자에서 떼가는 비율	10-35%
Collateral Factor	자산의 담보 가치 인정 비율	자산마다 다름

외워야 할 공식 3개

$$HF = \frac{LT}{LTV}$$$$\text{최대 허용 하락률} = 1 - \frac{LTV}{LT}$$$$\text{Supply APY} = \text{Borrow APR} \times \text{Utilization} \times (1 - \text{Reserve Factor})$$

세 번째 공식이 특히 중요하다. Supply APY가 Borrow APR보다 수학적으로 항상 작은 이유가 여기 있다. 풀의 돈이 100% 빌려진 게 아니고(Utilization < 1), 프로토콜이 Reserve Factor만큼 떼가기 때문이다.

단, 토큰 인센티브(COMP, AAVE)나 포인트/에어드랍까지 포함하면 역전될 수 있다. 2020년 DeFi Summer에 “빌리면 돈 버는” 상황이 실제로 발생했다.

이자율 모델: Jump Rate Model

“사용률이 올라가면 이자율도 올라간다"는 단순한 원칙이지만, 구현 방식은 프로토콜마다 다르다.

프로토콜	모델	특징
Compound V2	Jump Rate Model	원조. kink 지점에서 이자율 급등
Aave V3	Variable Rate Strategy	비슷하지만 파라미터 구조 다름
MakerDAO	거버넌스 직접 설정	알고리즘 아님
Euler V2	모듈형	풀 생성자가 모델 직접 선택

DEX에서 x * y = k (CPMM)가 원조 모델이듯, 렌딩에서는 Jump Rate Model이 원조다. “유일한 표준"은 아니지만, 대부분의 모델이 이걸 변형한 것이다.

cToken vs aToken: 이자를 반영하는 두 가지 방법

렌딩에 자산을 예치하면 “영수증 토큰"을 받는다. 이 영수증이 이자를 반영하는 방식이 Compound와 Aave에서 근본적으로 다르다.

Compound의 cToken: 교환비율 상승

1
2
3


예치: 1,000 USDC → 50,000 cUSDC (교환비율 0.02)
1년후: 50,000 cUSDC 그대로, 교환비율 0.025로 상승
인출: 50,000 × 0.025 = 1,250 USDC

토큰 수량은 변하지 않고, 교환비율이 올라간다.

Aave의 aToken: 잔고 자동 증가 (Rebase)

1
2
3


예치: 1,000 USDC → 1,000 aUSDC (1:1)
1년후: 지갑에 1,050 aUSDC로 자동 증가
인출: 1,050 aUSDC → 1,050 USDC

교환비율은 1:1 고정이고, 토큰 수량이 늘어난다.

비교	cToken	aToken
UX	비직관적 (교환비율 계산 필요)	직관적 (잔고 = 실제 가치)
DeFi 호환성	유리 (표준 ERC20)	불리 (rebase 토큰)
수학	`amount = shares × exchangeRate`	`balance = scaledBalance × index`

수학적으로는 동일하다. “언제 곱하느냐"의 차이일 뿐이다.

cToken의 교환비율 패턴은 사실 DeFi 전반에서 반복되는 범용 패턴이다.

1

지분으로 변환 → 전역 비율만 업데이트 → 인출 시 역변환

이 패턴을 쓰는 곳들:

프로토콜	용도
Compound cToken	렌딩 예치 영수증
ERC-4626	토큰화된 Vault 표준
Lido wstETH	Liquid Staking
Rocket Pool rETH	Liquid Staking
Walrus StakingPool	스토리지 네트워크 스테이킹

Walrus의 StakingPool과 비교하면:

1
2
3
4
5
6
7
8
9


Compound cToken:
 exchange_rate = (totalCash + totalBorrows - totalReserves) / totalSupply
 deposit: shares = amount / exchange_rate
 withdraw: amount = shares × exchange_rate

Walrus StakingPool:
 exchange_rate = total_wal / total_shares
 stake: shares = principal × total_shares / total_wal
 withdraw: amount = shares × total_wal / total_shares

같은 공식이다. 변수명만 다르다.

가스 최적화의 핵심: Scaled Balance

aToken이 “잔고가 자동으로 늘어난다"면, 매번 모든 사용자의 잔고를 업데이트하는 걸까? 당연히 아니다. 그러면 가스비가 폭발한다.

핵심 아이디어: 쓰기를 읽기로 바꾼다.

1

Scaled Balance = 예치금 / 예치 시점의 liquidityIndex

이 값은 한번 저장되면 절대 변하지 않는다. 변하는 건 전역 liquidityIndex 하나뿐이다.

잔고를 조회할 때 scaledBalance × 현재 index로 계산한다. balanceOf()는 view 함수이므로 가스비가 0이다.

1
2
3
4
5
6


순진한 방식: 이자 발생 시 모든 사용자 잔고 SSTORE
 → 1,000명 × 5,000 gas = 5,000,000 gas

Scaled Balance: 전역 index 1개만 SSTORE
 → 5,000 gas
 → 99.9% 절약

EVM에서 SSTORE(쓰기)는 5,000 gas, MUL(곱셈)은 5 gas다. 쓰기는 계산보다 1,000배 비싸다. Merkle Patricia Trie를 재계산하고 모든 노드에 영구 저장해야 하기 때문이다. Scaled Balance는 이 비용 구조를 정확히 활용한 최적화다.

Compound V2 vs Aave V3: 아키텍처 차이

두 프로토콜의 가장 큰 차이는 코드 구조에 있다.

1
2
3
4
5


Compound: CToken이 풀 역할까지 겸함 (Monolithic)
 사용자 → CToken.mint()

Aave/우리 프로젝트: Pool과 토큰 분리 (Modular)
 사용자 → Pool.deposit() → aToken.mint()

Compound의 CToken은 ERC20 토큰이면서 동시에 렌딩 풀이다. mint(), borrow(), repay(), liquidate() 모두 CToken 컨트랙트에 있다. 반면 Aave는 Pool이 중심이고 aToken은 순수한 영수증 토큰이다.

Compound V2 코드 리딩 가이드

Compound V2 코드를 읽고 싶다면, 핵심 3개 파일, 5개 함수만 보면 된다.

CToken.sol - 핵심 함수 5개:

accrueInterest() - 이자 누적 (borrowIndex = scaled balance 패턴)
mintFresh() - 예치
borrowFresh() - 대출
repayBorrowFresh() - 상환
liquidateBorrowFresh() - 청산

Comptroller.sol - 핵심 함수 1개:

getHypotheticalAccountLiquidityInternal() - Health Factor 계산

BaseJumpRateModelV2.sol - 이자율 모델

나머지(Governance, Lens, Timelock 등)는 렌딩 로직과 무관하므로 무시해도 된다.

이자율의 3개 레이어

DeFi에서 실제 수익률은 단순한 이자율이 아니라 3개 레이어의 합이다.

1
2
3


Layer 1: 기본 이자 → Jump Rate Model이 결정
Layer 2: 토큰 인센티브 → COMP, AAVE 등 거버넌스 토큰 보상
Layer 3: 포인트/에어드랍 → Blast, EigenLayer 등

Layer 2, 3까지 포함하면 “빌리면 돈 버는” 상황도 발생한다. 2020 DeFi Summer에 COMP 보상이 대출 이자보다 커서 Compound에서 빌리는 것 자체가 수익이었던 것이 대표적인 사례다.

Day 1 핵심 인사이트 정리

렌딩의 본질은 풀 기반 중개 - 예치자와 대출자를 직접 매칭하지 않고, 풀을 통해 간접 매칭한다. 스테이킹 풀과 동일한 패턴.
Share-Based Accounting은 DeFi의 범용 패턴 - cToken, ERC-4626, wstETH, rETH, Walrus 전부 같은 원리. “지분으로 변환 → 전역 비율만 업데이트 → 인출 시 역변환.”
가스 최적화의 핵심은 “쓰기를 읽기로 바꾸기” - SSTORE는 계산보다 1,000배 비싸다. Scaled Balance 패턴으로 전역 index 하나만 업데이트하고 나머지는 읽기 시점에 계산.
Compound는 Monolithic, Aave는 Modular - CToken이 풀 겸 토큰 vs Pool과 토큰 분리.
실제 수익률 = 기본 이자 + 토큰 인센티브 + 포인트 - 3개 레이어를 모두 봐야 DeFi의 실제 경제를 이해할 수 있다.

Next: Day 2

내일은 Aave V3 아키텍처를 코드 레벨로 들어간다.

Pool.sol, SupplyLogic.sol, BorrowLogic.sol, LiquidationLogic.sol 리딩
Fork Testing으로 Aave V3 메인넷 상태에서 직접 테스트
Fuzz Testing으로 이자율 엣지 케이스 탐색