ZGBA-1R 기술 백서

01범위와 계약 식별

본 문서는 Solidity·ERC-20의 기본 동작을 이해하는 개발자와 기술 검토자를 대상으로 한다. 이더리움 메인넷에 배포된 단일 컨트랙트 ZGBA1R의 식별자, 총공급량·잔액·사용 한도의 상태 전이와 외부 시스템에 대한 의존성을 기술한다. 운영 방향과 용도별 배정 계획은 일반 백서에서 다룬다.

• 배포 계약 · 소스 · ABI ↗
• 배포 거래 ↗
• ERC-20 표준 ↗

02상태와 불변식

A는 주소 집합, B(a)는 주소 a의 잔액, L(o,s)는 보유자 o가 전송 권한을 부여한 주소 s의 사용 한도, S는 총공급량을 나타낸다. 모든 수량은 최소 단위의 uint256 정수로 표현하며, 표현 범위는 0부터 2²⁵⁶−1까지이다. 1 ZGBA는 최소 단위 10¹⁸개에 해당한다. 생성자는 서로 다른 유효 수령인 d와 r에 다음 수량을 발행한다.

S = 1,000,000 × 10¹⁸ = 10²⁴
B(d) = 2 × 10²³; B(r) = 8 × 10²³
Σ B(a) = S; 0 ≤ B(a) ≤ S
∀ n ≥ 0: S(n) = S(0)

Σ는 모든 주소에 대한 잔액의 합을, n은 배포 후 상태 전이 횟수를 나타낸다. 공급량 변경은 생성자의 두 _mint 호출에서만 발생한다. 배포 후 실행 가능한 함수에는 추가 발행·소각·업그레이드 경로가 없다.

성공한 전송에서는 동일 수량을 송신 주소에서 차감하고 수령인 주소에 가산한다. 자기 자신으로의 전송에서는 잔액의 순변화가 0이다. 승인은 잔액을 이동시키지 않으며 실패한 호출은 상태 변경을 되돌리므로, 각 전이에서 최초 총공급량이 보존된다.

• 배포 계약 · 소스 · ABI ↗
• OpenZeppelin · ERC20 소스 v5.6.1 ↗

03전송·승인과 실패 시 상태 보존

from은 송신 주소, to는 수령인 주소, v는 최소 단위 수량을 나타낸다. transfer(to,v)는 호출자의 잔액 중 v를 전송하며, transferFrom(from,to,v)는 호출자가 from으로부터 승인받은 한도 내에서 v를 전송한다. 두 함수 모두 유효한 수령인과 충분한 잔액을 요구한다.

approve(spender,v)는 호출자가 spender에 부여한 사용 한도를 v로 설정하며, 기존 한도에 v를 가산하지 않는다. 한도가 uint256 최댓값인 경우에는 무제한 승인으로 취급하여 위임 전송 후에도 차감하지 않는다. 그 밖의 경우에는 성공한 위임 전송의 수량만큼 한도를 차감한다.

transfer: B(a)′ = B(a) − v·1[a = from] + v·1[a = to]
approve: L(owner, spender)′ = v
transferFrom: L′ = L − v  (L ≠ 2²⁵⁶ − 1)
revert: state′ = state

위 식에서 ′는 실행 후 상태를 나타내며, 1[조건]은 조건이 참이면 1, 거짓이면 0이다. revert는 실패한 호출의 상태 변경을 되돌리므로 잔액·한도·이벤트가 일부만 적용된 상태로 남지 않는다. 다만 블록에 포함된 실패 거래도 가스비와 발신 계정의 거래 순번(nonce)을 소비할 수 있다.

영 주소와 토큰 컨트랙트 자체는 전송 수령인으로 허용되지 않는다. 다른 수령 컨트랙트의 토큰 인출 가능 여부는 검사하지 않는다. 유효한 주소 간의 수량 0 전송과 자기 자신으로의 전송은 허용되며, Transfer 이벤트를 기록한다. 위임 전송에서는 자기 자신에게 전송하더라도 유한 한도가 차감된다.

approve는 영 주소를 승인 대상으로 허용하지 않으며, 성공 시 Approval 이벤트를 기록한다. 위임 전송에 따른 유한 한도의 차감에는 별도의 Approval 이벤트가 기록되지 않으므로, 현재 한도는 allowance(o,s)로 조회해야 한다.

승인은 자동으로 만료되지 않는다. 기존 한도의 변경이 처리되기 전에 승인받은 주소가 이전 한도를 사용할 수 있으므로, 한도를 먼저 0으로 설정하여 철회하고 처리 결과를 확인하는 절차를 권장한다. 이는 클라이언트의 권장 절차이며 approve가 강제하는 선행 조건은 아니다. 철회 전에 실행된 전송은 취소되지 않는다. 서명을 기반으로 승인을 제출하는 EIP-2612 permit 기능은 지원하지 않는다.

• ERC-20 표준 ↗
• OpenZeppelin · ERC20 소스 v5.6.1 ↗

04클라이언트와 거래 확정

표시 수량 q와 최소 단위 수량 v의 관계는 v = q × 10¹⁸이다. v는 0 이상인 uint256 정수여야 하며, 전송량은 잔액을 초과할 수 없다. 클라이언트는 소수 입력을 최소 단위의 정수로 변환하고, 소수점 이하 유효 자릿수가 18자리를 초과하는 입력, 지수 표기, 음수와 잘못된 값을 거부한다. 서명에 앞서 지갑에 표시된 수령인·수량·네트워크를 확인해야 한다.

거래 준비, 지갑 서명, 네트워크 제출, 블록 포함과 최종 확정은 서로 다른 상태이다. 거래 해시는 식별자이며 실행 성공을 뜻하지 않는다.

거래 영수증의 status와 blockHash, 실제 거래의 체인·발신자·대상·수량·nonce 및 Transfer·Approval 로그를 서명 전 검토한 내용과 대조한다. 위임 한도는 확정 블록에서 다시 조회한다. 제공 클라이언트는 응답 누락·시간 초과·거래나 로그의 불일치를 확인 불가로 처리한다.

최종 확정 여부는 RPC가 보고한 finalized 블록의 높이가 거래 포함 블록 이상인지 확인하고, 각 블록의 해시가 해당 높이의 정규 체인 조회 결과와 일치하는지 대조하여 판정한다. finalized 조회를 지원하지 않는 RPC에서는 블록 포함 상태만 표시하고 최종 확정으로 처리하지 않는다.

서명은 외부 지갑에서 처리하며, 클라이언트는 개인키와 복구 구문을 입력받지 않는다. RPC는 체인 조회와 거래 제출을 위한 노드 접속 인터페이스이다. 응답 대조 시에는 독립된 제공자의 응답을 동일한 블록 기준으로 비교한다.

• Ethereum · 가스와 수수료 ↗
• Ethereum · 합의 ↗

05경매 배정과 외부 계약의 회계

r은 생성자 인자 distribution에 해당한다. 경매 생성 거래에서 r의 기존 물량 800,000 ZGBA가 경매 계약과 유동성 공급용 계약으로 이전됐다. 다음 식은 생성 거래의 Transfer 로그에 기록된 ZGBA 표시 수량이며 현재 잔액이나 유통량은 아니다.

가격·입찰 규모·판매 비율과 LP 조건은 확인 시점의 Uniswap 화면 표시다. 경매 종료와 청구 시작은 블록 기준이며 날짜는 예상치다. LP 약정 비율은 총공급량 중 ZGBA 배정 비율과 구분하며, 잠금 기한 표시만으로 풀 생성·예치·포지션 잠금 완료를 확인한 것은 아니다.

• Uniswap · ZGBA 경매 ↗
• 경매 생성 거래 · 배정·이벤트 ↗

Qdeveloper_initial = 200,000 ZGBA
Qauction_deposit = 601,503.759398496240601504 ZGBA
Qliquidity_allocation = 198,496.240601503759398496 ZGBA
Qauction_deposit + Qliquidity_allocation = 800,000 ZGBA
Qdeveloper_initial + Qauction_deposit + Qliquidity_allocation = 1,000,000 ZGBA

경매 일정의 start, end, claim은 각각 시작·종료·청구 시작 블록을 나타내며, start < end ≤ claim을 충족해야 한다. 각 단계의 mps는 전체 경매 물량을 기준으로 한 블록당 배정 비율을 1/10,000,000 단위로 표현한다. 예를 들어 100블록 동안 mps=100,000을 적용하면 전체 경매 물량에 해당한다. 단계별 mps × 블록 수의 합은 10,000,000이어야 하며, 블록 수의 합은 end − start와 같아야 한다.

이 일정은 기존 경매 물량의 배정을 나타내며, 신규 발행이나 개발자 물량의 베스팅을 뜻하지 않는다. 결제 자산, 환불, 미판매분과 반올림 잔여분은 경매 규칙에 따라 별도로 정산한다.

경매는 진행 중이다. 유동성 공급용 계약은 0x2EEF0e2a9a652d755AccAD95a24541A98B5CA000다. 이 주소로의 전송은 풀 예치·LP 포지션 생성·잠금 완료를 입증하지 않는다. 생성 시 배정 합계와 현재 보유량, 실제 정산·청구 수량을 구분한다.

• Uniswap · CCA 소스 v2.1.0 ↗

06코드 동작과 온체인 상태 검증

코드 동작 시험과 배포 상태 조회는 별도로 수행한다. 컨트랙트는 체인 ID와 주소를 함께 확인하여 식별하며, 이름·기호만으로 식별하지 않는다.

동작 시험의 조건과 결과

공개 네트워크에 접속하지 않은 EthereumJS 10.1.3의 Prague EVM에서 시험용 계정으로 계약을 생성하였다. 시험 계약의 실행 바이트코드 해시는 본문에 명시한 런타임 코드 해시와 일치한다. 검증 입력을 재컴파일하여 ABI·생성 바이트코드·실행 바이트코드가 빌드 산출물과 일치하는지도 확인하였다.

아래 시나리오를 실행한 범위에서는 기대한 상태 전이와 불일치가 발견되지 않았다. RPC 항목은 응답을 모의한 클라이언트 시험이며 실제 제공자의 가용성 측정은 아니다.

배포 상태 조회 절차

다음 조회는 체인에 접근할 수 있는 노드에서 동일한 확정 블록을 기준으로 수행한다. 각 결과에는 체인, 컨트랙트, 블록 번호·해시와 조회 시점을 함께 기록한다.

• 배포 계약 · 소스 · ABI ↗
• 배포 거래 ↗