개발자

전체 참조

모든 경로와 매개변수, 응답 형식:

API 참조 열기 →  ·  다른 보기

두 주소 모두 같은 문서를 제공합니다.

다운로드

운영자가 이 게이트웨이에 게시한 파일은 /dl/<name>에서 제공됩니다. 이름은 [A-Za-z0-9._-]의 단일 세그먼트이며, 모든 파일은 렌더링되지 않고 항상 첨부 파일로 전송됩니다. 이 출처는 지갑도 제공하므로, 여기서 렌더링된 페이지는 지갑의 출처를 물려받게 되기 때문입니다.

릴리스 번들은 /releases/<version>/<arch>/ 아래에 있으며, /releases/latest가 현재 번들을 가리킵니다. 노드 설치 프로그램 위치: /install.

이 게이트웨이는 정상인가요? 확인 중…

/gateway/status 이 게이트웨이가 자신과 자신이 접근할 수 있는 노드에 대해 알고 있는 정보, 즉 모드, 도메인, 허용 목록의 노드 수, 응답 중인 노드를 보고합니다.

/gateway/system-stats 머신 정보, 즉 CPU, 메모리, 디스크, 가동 시간을 보고합니다. 게이트웨이 페이지의 수치는 여기서 가져옵니다.

curl https://this-gateway/gateway/status
curl https://this-gateway/gateway/system-stats

둘 다 키가 필요 없습니다. 둘 다 체인에 관한 정보는 노출하지 않으므로, 체인 정보가 필요하면 위의 /api/v1/…를 사용하세요.

특정 노드에 접근하기

체인 경로는 이 게이트웨이가 고른 아카이브 노드가 응답합니다. 특정 노드에 질의하려면 호스트 이름에 그 노드의 IP를 넣으세요. 점은 대시로 바뀌며, 선택 사항인 -p<port>로 API 포트를 지정합니다:

curl https://ip-192-168-1-100.this-gateway/api/v1/node/info
curl https://ip-192-168-1-100-p8080.this-gateway/api/v1/node/info

이 게이트웨이의 허용 목록에 있는 노드만 응답합니다. 그 밖의 대상은 프록시되지 않고 거부되므로, 호스트 이름을 이용해 게이트웨이를 거쳐 임의의 호스트에 접근할 수 없습니다.

릴레이

음성, 영상, 화면 공유는 P2P로 이루어집니다. 방화벽이 직접 연결을 막으면 릴레이가 크레딧을 받고 트래픽을 전달합니다. /relay/info는 릴레이의 주소, 요금, 정산하는 체인의 제네시스 해시를 보고하며, 지갑은 지불하기 전에 이를 자신의 노드와 대조합니다. 다른 체인의 릴레이는 받은 대금을 크레딧으로 반영할 수 없기 때문입니다.

curl https://this-gateway/relay/info

관리자 패널

게이트웨이 자체의 제어 기능은 zoobc.network/admin에 있습니다. /etc/zoobc/gateway.json의 admin_api_key로 보호되며, 이 키는 설치 프로그램이 서버마다 생성합니다. 기본 키는 없습니다.

허용 목록

게이트웨이는 등록된 노드로만 프록시합니다. 이 목록이 있기에 ip-… 호스트 이름 형식이 게이트웨이를 개방형 프록시로 만들지 못합니다.

세 가지 쓰기 작업 모두 관리자 키가 필요합니다. 공개 모드에서는 게이트웨이가 체인 자체의 레지스트리에서도 노드를 찾고, 비공개 모드에서는 다음만 사용합니다: static_nodes.

릴리스 도구

파일 해셔는 직접 확인하고 싶은 어떤 파일이든 브라우저에서 SHA-256을 계산하고, /verify는 내려받은 번들을 체인이 게시한 해시와 대조합니다.

두 문서

하드웨어 지갑 팀에 필요한 모든 것이 여기에 명시되어 있으며, 전체 내용은 아래 두 PDF에 있습니다. 두 문서 모두 ZooBC 노드 v0.4.0(7ad161a4 시점의 zoobc-main)과 실제 v0.4.0 노드가 수락한 트랜잭션 벡터로 검증되었습니다.

버전 2.1은 한 가지 실질적인 점에서 초안 1을 대체합니다. 이제 트랜잭션 서명이 체인에 바인딩됩니다. 초안 1을 기준으로 개발했다면 서명 다이제스트와 ApprovalEscrow 바디, 이 두 가지가 호환되지 않게 바뀌었습니다. 예전 v0.3.2 구성을 구현한 곳은 없으므로 현재 문서만을 기준으로 개발하세요.

한 페이지 요약

이 네 가지를 먼저 읽으세요

구현에 다른 무엇보다 큰 영향을 주는 네 가지 사항.

키 파생과 주소

참조: zoobc-signer/extension/lib/zoobc-crypto.js, 참조 지갑과 바이트 단위로 동일합니다. 노드 측 대응 구현 위치: src/crypto/slip10.cpp.

seed = PBKDF2-HMAC-SHA512(NFKD(mnemonic), "mnemonic" + passphrase, 2048, 64)
I    = HMAC-SHA512("ed25519 seed", seed);  k = I[0..32], c = I[32..64]

for index in [44, 883, account]:                       # all hardened
    data = 0x00 || k || u32be(index + 0x80000000)
    I    = HMAC-SHA512(c, data);  k = I[0..32], c = I[32..64]

pubkey = Ed25519.publicKeyFromSeed(k)                  # k is the 32-byte seed

계정 0은 m/44'/883'/0', 계정 1은 m/44'/883'/1', 이런 식으로 이어집니다. 키 파생은 체인 바인딩의 영향을 받지 않습니다. 하나의 키 세트가 모든 ZooBC 체인에 쓰이며, 달라지는 것은 서명뿐입니다.

표시용 주소는 36바이트 계정이 아니라 공개 키로 만듭니다:

buf[35] = pubkey(32) || "ZBC"
h       = SHA3-256(buf);  buf[32..35] = h[0..3]        # 3-byte checksum
s       = base32(buf)                                   # RFC 4648 A-Z2-7, no padding, 56 chars
address = "ZBC_" + s[0..8] + "_" + s[8..16] + ...       # 7 groups, canonical length 66

디코딩 시 밑줄, 대시, 공백 또는 구분자 없음을 모두 허용하며 대소문자도 구분하지 않습니다. 체크섬은 다시 계산해 비교해야 합니다. 위의 3바이트 SHA3 체크섬이 코드와 체인이 사용하는 정의이므로, 이 정의와 명세서의 참조 구현(예시 주소를 그대로 재현합니다)을 바탕으로 구현하세요.

서명되지 않은 트랜잭션의 전송 형식

기준 소스: src/util/transaction_util.cpp:144-270. 전송 형식은 v0.4.0에서 바뀌지 않았습니다. 아래의 길이나 오프셋 중 체인 바인딩의 영향을 받는 것은 없습니다.

에스크로 블록 끝의 multi_party 바이트는 필수입니다. 이를 생략하거나 에스크로 없음 표시를 다른 값으로 쓰면, 노드에서 다른 진단 정보 없이 "Invalid transaction signature"만 반환됩니다.

체인에서 검증된 실제 예제

자기 자신에게 1 ZBC를 보내는 SendZBC, 수수료 0.05 ZBC, 타임스탬프 1700000000, 에스크로 없음, 메시지 없음. 명세서에 있는 벡터 7개 중 벡터 0입니다.

01000000                 type = 1 (SendZBC)
01                       version
00f1536500000000         timestamp 1700000000
00000000 5e8eb28d...2152 sender    (type 0 + pubkey)
00000000 5e8eb28d...2152 recipient (type 0 + pubkey)
404b4c0000000000         fee 5 000 000
08000000                 body length 8
00e1f50500000000         body: amount 100 000 000
02000000                 no-escrow marker
00000000                 message length 0

총 113바이트입니다. 서명 프리이미지는 그 앞에 38바이트를 더 붙입니다:

5a42432d5458              tag "ZBC-TX"          6 bytes
090ab3c7...a61878         genesis hash         32 bytes
0100000001...00000000     the 113 bytes above 113 bytes
                                              ---------
                                              151 bytes

digest = SHA3-256(preimage) = f37e5340...4644fc, 서명 9a3b044d...03bb07, tx_hash = f00a6692...ce78b0. 실제 v0.4.0 노드가 HTTP 202와 정확히 이 해시를 반환했습니다.

서명 절차(기기 측)

input : account_index, genesis_hash(32), unsigned_bytes

1. k      = SLIP10(m/44'/883'/account_index')
2. pub    = Ed25519.pub(k);  self = 00000000 || pub
3. parse unsigned_bytes; every length must land exactly at the end
4. require version == 1 and sender == self
5. decode body per type; render the approval screen; wait for the user
6. digest = SHA3-256("ZBC-TX" || genesis_hash || unsigned_bytes)
7. sig    = Ed25519.sign(k, digest)          # the digest IS the message
8. return sig(64), and tx_hash = SHA3-256(unsigned_bytes || sig) for the host to cross-check

6단계에서 전체 트랜잭션을 RAM에 올리지 않아도 되도록 스트리밍 SHA3를 사용하세요. 태그 6바이트, 제네시스 32바이트, 그다음 트랜잭션 순서로 입력합니다.

명세서 전체에서 구현 오류가 가장 많이 나올 만한 부분이 바로 태그입니다. "ZBC-TX"는 ASCII 6바이트 5a 42 43 2d 54 58이며, NUL 종료 문자도 길이 접두사도 없습니다. 문자열에 종료 문자를 붙이거나 7바이트를 쓰는 펌웨어는 정상처럼 보이는 서명을 만들지만, 체인에서는 진단 정보 없이 일반적인 오류로 실패합니다. 무엇보다 먼저 벡터 0으로 테스트하세요.

체인 바인딩이 하는 일과 하지 않는 일

제네시스 32바이트는 호스트가 제공하며, 기기가 조회하지 않습니다. 따라서 서명은 체인에 구애받지 않으며, 하나의 코드 경로로 TestNet, devnet, MainNet은 물론 모든 비공개 또는 병렬 ZooBC 체인을 지원합니다.

따라서 알려진 제네시스 해시를 담은 펌웨어 테이블은 여전히 필요하지만, 용도는 하나뿐입니다. 화면에 신뢰할 수 있는 네트워크 이름을 표시하고, 해시가 테이블에 없으면 "UNKNOWN CHAIN"과 처음 8자리 hex를 대신 표시하는 것입니다.

인식되지 않는 체인을 기본적으로 거부하지 마세요. devnet의 해시는 다시 시작할 때마다 바뀌고 ZooBC에서는 비공개 또는 병렬 체인이 흔하므로, 무조건 거부하면 통합 작업에도 정당한 배포에도 기기를 쓸 수 없게 됩니다. 공급업체가 그런 잠금을 원한다면 기본값이 꺼짐인 명시적 사용자 설정으로 만드세요.

트랜잭션 유형: 표준 펌웨어가 지원해야 할 것

유형 id = group + 256 × subtype. 유형은 56가지가 있습니다. 이 세 가지로 ZBC 지불, 모든 토큰 지불, 에스크로 완료를 처리할 수 있으며, 바디는 작고 길이가 고정되어 있습니다.

token_id 는 해시에서 파생된 부호 있는 64비트 값이므로 음수일 수 있습니다. 제네시스 코인은 id 1부터 14까지이고, ZBC 자체는 id 0이며 TransferToken에는 절대 나타나지 않습니다. 각 토큰에는 기기가 검증할 수 없는 고유한 decimals(0부터 8)가 있습니다.

ApprovalEscrow는 v0.4.0에서 바뀌었습니다. 바디는 원래 approval와 8바이트 id(12바이트)였지만, 이제는 approval와 에스크로된 트랜잭션의 32바이트 해시(36바이트)이며, 파서는 다른 길이를 모두 거부합니다. 바로 하드웨어 지갑 때문에 바뀐 것입니다. 8바이트 id만 보는 서명자는 자신이 무엇을 해제하는지 확인할 수 없었고, 8바이트 id는 기기에 보여 줄 가짜 에스크로를 상대로 2^64 탐색을 하면 찾아낼 수 있습니다. 전체 해시가 있으면 기기는 자신이 승인하는 대상을 검증할 수 있습니다.

기기가 검증하는 것

사용자가 화면에서 승인하는 내용

체인에서 검증된 참조 서명기를 바탕으로, 화면별로 다음 순서를 따릅니다.

타임스탬프는 표시할 필요가 없습니다. 사용자에게 의미 있는 정보가 아니며, 포함 기간은 노드가 강제합니다.

호스트와 기기 간 프로토콜

전송 계층은 공급업체 자체의 USB/HID 계층과 기존 청크 분할 방식을 사용합니다. 중요한 것은 내용입니다.

genesis_hash는 표시용 힌트가 아니라 결과를 좌우하는 값입니다. 초안 1에서는 네트워크 매개변수가 라벨만 고르는 용도였기 때문에 열거형이어도 됐습니다. 이제는 다이제스트 안에 들어가므로 실제 32바이트여야 하며, 잘못된 값을 넣으면 어떤 체인도 받아들이지 않는 서명이 만들어집니다.

원시 서명 규칙. 원시 서명 명령은 정확히 32바이트인 입력에 절대 서명해서는 안 되며, 텍스트로 표시할 수 있는 입력에만 서명해야 합니다. 32바이트 원시 입력은 사용자가 본 적 없는 트랜잭션의 SHA3 다이제스트일 수 있고, 그러면 메시지 명령이 내용을 보지 않고 하는 트랜잭션 서명으로 바뀝니다. 길이 32를 거부하면 체인을 변경하지 않고도 이 허점을 막을 수 있습니다.

전체 순서

Website (page)         Companion / host           device                    Gateway / node
   |-- connect ---------->|                            |                          |
   |                      |-- GET_PUBLIC_KEY(0) ----->|  (shows ZBC_... address) |
   |<-- address ----------|<-- pubkey, address -------|                          |
   |-- GET /api/v1/node/info  (genesis_hash, signing_version, height) ---------->|
   |-- GET /api/v1/accounts/<addr>  (balances) --------------------------------->|
   |-- GET /api/v1/accounts/<addr>/tokens, /api/v1/tokens/<id> (decimals) ------>|
   |   user fills the form                             |                          |
   |-- GET /api/v1/blockchain/estimate-fee?type=1&body_length=8 ---------------->|
   |<-- {minimum_fee, timestamp} ------------------------------------------------|
   |-- fields {type, recipient, body, fee, message} -->|                          |
   |                      |  serialize the 11 fields   |                          |
   |                      |-- SIGN_TX(0, genesis, -->|  parse, verify, display,  |
   |                      |            bytes)         |  user approves            |
   |                      |<-- signature, tx_hash ---|                          |
   |<-- signature --------|                            |                          |
   |-- POST /api/v1/transactions {JSON} ---------------------------------------->|
   |<-- 202 {status:"success", transaction_hash} --------------------------------|
   |-- GET /api/v1/transactions/<hash>/status  (staging, mempool, confirmed) --->|

호스트는 노드의 transaction_hash를 기기의 tx_hash와 비교합니다. 두 값은 같아야 하며, 다르면 호스트가 서명 후에 바이트를 변경한 것입니다.

브로드캐스트할 엔드포인트에서 genesis_hash와 signing_version를 읽으세요. 서명을 판정하는 것은 그 체인이기 때문입니다.

체인 식별

ZooBC의 유일한 네트워크 식별자는 제네시스 블록 해시입니다. 노드는 피어 연결 전에 이를 비교하며, 네트워크 ID 바이트는 없습니다. GET /api/v1/node/info는 v0.4.0에서 새로 추가된 두 필드와 함께 이를 반환합니다:

"genesis_hash": "090ab3c7...", "signing_version": 2, "signing_tag": "ZBC-TX"

signing_version 이 필드가 없으면 노드가 v0.4.0 이전 버전이며 바인딩되지 않은 레거시 다이제스트를 강제한다는 뜻입니다. 현재 체인만 지원하는 호스트는 이 필드가 없을 때 "여기서는 서명하지 않음"으로 처리할 수 있습니다. 노드는 소문자 hex를, 아카이브 API는 대문자 hex를 출력하므로 대소문자를 구분하지 않고 디코딩하고, 앞에 0x가 있으면 제거하세요. 어느 쪽이든 바이트는 같습니다.

어디서 읽을 것인가. 게이트웨이는 /api/v1/node/info에 노드가 아니라 아카이브 서비스로 응답합니다. 아카이브는 빌드 7ad161a4부터 자신이 미러링하는 노드의 두 서명 필드를 그대로 전달하며, 노드가 보고할 때에만 정확히 내보냅니다. signing_version는 노드 엔드포인트나 해당 빌드 이상의 게이트웨이에서 읽고, 필드가 없으면 그것을 답으로 여기지 말고 "노드에 물어보라"는 뜻으로 받아들이세요.

브로드캐스트

POST /api/v1/transactions. v0.4.0에서 변경 없음, 새 필드 없음. transaction_body_bytes는 바디만 담습니다. 노드는 이름 있는 필드들로 엔벨로프를 재구성하고, 자신의 제네시스 해시와 태그를 앞에 붙여 다이제스트를 다시 계산하므로, 모든 필드가 서명한 값과 같아야 합니다.

{
  "version": 1,
  "timestamp": 1700000000,
  "transaction_type": 1,
  "fee": 5000000,
  "sender_account_address":    "00000000 5e8eb28d ... 2152",
  "recipient_account_address": "00000000 5e8eb28d ... 2152",
  "transaction_body_bytes": "00e1f50500000000",
  "signature": "9a3b044d ... 03bb07",
  "message_hex": "...optional...",
  "escrow": { "approver_address": "...", "commission": 0, "timeout": 1700003600 }
}

성공하면 HTTP 202와 {"status":"success","duplicate":false,"transaction_hash":"..."}가 반환됩니다. duplicate:true는 노드가 이미 해당 트랜잭션을 보유하고 있다는 뜻이므로 다시 보내지 마세요. 200도 성공으로 처리하세요. 실패하면 오류 본문과 함께 400이, 부하가 높을 때는 503이 반환됩니다.

유용한 통합 테스트: 스테이징 풀은 서명을 먼저 확인하므로, "Sender account does not exist" 같은 이후 단계의 오류에 도달한 트랜잭션은 이미 서명 검증을 통과한 것입니다. 잔액이 없는 키로도 서명 경로를 검증할 수 있습니다.

서명이 거부될 때

현재로서는 체인 불일치를 다른 서명 실패와 구별할 수 없습니다. 레거시 다이제스트와 잘못된 체인의 다이제스트 모두 동일한 본문을 반환합니다:

{"success":false,"error":"Transaction validation failed: ValidationError: Invalid transaction signature","code":400}

따라서 가능성이 가장 높은 것부터 다음 순서로 원인을 점검하세요:

개발 대상 엔드포인트

읽기 요청은 아카이브, 게이트웨이, 노드 순으로 라우팅하세요. 브로드캐스트는 게이트웨이나 노드로 보내고, 아카이브 엔드포인트로는 절대 보내지 마세요.

제네시스 해시는 런타임에 읽고, 하드코딩하지 마세요. devnet의 해시는 재시작할 때마다 바뀝니다. 펌웨어의 해시 테이블은 화면에 이름을 표시하기 위해서만 존재하므로, 오래된 항목은 서명을 망가뜨리지 않고 “UNKNOWN CHAIN” 표시로 격하될 뿐입니다. devnet의 해시가 실제로 바뀌면 그 이전에 만든 모든 서명은 무효가 되며, 이는 기능이 의도대로 작동하고 있다는 뜻입니다.