ZooBC 위키
통합

노드 API

모든 ZooBC 노드는 하나의 공개 HTTP API를 제공합니다. 지갑, 익스플로러, 명령줄 도구, 그리고 어떤 웹 페이지든 이를 통해 체인을 읽고 트랜잭션을 제출합니다. 읽기에는 키도, 계정도, API 키도 필요 없으며, API는 어디에 호스팅된 페이지에든 응답합니다. 쓰기에는 송신자가 서명한 트랜잭션만 있으면 됩니다.

기본 사항

  • 위치: 기본적으로 포트 8080의 평문 HTTP/1.1이며, /api/v1/ 아래에 백 개가 넘는 경로가 있습니다. 노드는 /와 /wallet에서 웹 지갑도 제공합니다.
  • 노드에는 TLS가 없음: 공개 사이트는 게이트웨이를 거쳐 HTTPS로 API에 닿으며, 게이트웨이는 깊은 이력을 위해 아카이브 서비스도 앞에 둡니다.
  • 모든 페이지에 열려 있음: 모든 응답에 Access-Control-Allow-Origin: *가 붙고 브라우저의 OPTIONS 검사에는 즉시 응답하므로, 어느 도메인의 페이지든 API를 호출할 수 있습니다(HTML 페이지 하나로 앱 만들기).
  • 대부분 읽기: 여덟 개를 제외한 모든 경로는 인증이 필요 없는 읽기입니다. 트랜잭션 제출에는 API 키가 필요 없습니다. 트랜잭션이 자체 서명을 담고 있기 때문입니다.
  • 클라이언트 주소별 한도: 쓰기 요청은 기본적으로 분당 300회이며(넘으면 노드는 Retry-After 헤더와 함께 429로 응답합니다), 읽기는 운영자가 한도를 정하지 않는 한 무제한입니다.
HTML 페이지 하나가 GET 요청으로 체인을 읽고, 서명된 바이트를 노드나 게이트웨이에 제출합니다. API는 모든 출처에 응답합니다
HTML 페이지 하나가 GET 요청으로 체인을 읽고, 서명된 바이트를 노드나 게이트웨이에 제출합니다. API는 모든 출처에 응답합니다

읽을 수 있는 것

영역예
노드와 체인/api/v1/node/info(genesis_hash와 signing_version 포함), /api/v1/blockchain/rules
계정/accounts/:address(잔액, 지출 가능액, 잠긴 스테이크), /history, /transactions, /movements, /datasets, /escrows, /group, /pubkey
트랜잭션/transactions/:hash/status
노드 레지스트리/nodes?status=all, /nodes?status=queued
서비스 레지스트리/registry/gateways, /registry/archivals, /registry/relays
릴리스/release/list, /release/authority
앱/apps, /apps/open, /apps/pool, /apps/stats, /apps/:id
브리지/bridge/coins, /bridge/withdrawals/:hash
스파인/spine/blocks/:height

두 번째 열의 모든 경로는 /api/v1/ 아래에 있습니다. /movements는 계정 잔액의 모든 변화를 원인과 함께 보여 주며, 낸 임대료와 받은 보상도 포함합니다. /pubkey는 네이티브 계정의 공개 키를 주소만으로 돌려줍니다. 버전 0.5.8부터 체인 경로는 finalized_height를, 각 트랜잭션은 finalized 플래그를 알려 주며, 이 플래그는 공동 서명된 스파인 블록이 그 블록을 포함하면 설정됩니다(최종성과 롤백).

누구나 이런 방식으로 어떤 주소든 조회할 수 있습니다. 체인은 이름이 아니라 키를 기록하므로, ZooBC에서의 프라이버시는 숨겨진 잔액이 아니라 주소를 어떻게 쓰느냐에서 나옵니다(계정과 주소).

트랜잭션 제출하기

클라이언트는 트랜잭션의 바이트를 만들고, /api/v1/node/info에서 읽은 genesis_hash를 써서 송신자의 키로 체인 결속 다이제스트에 서명한 뒤(트랜잭션 서명), 그 결과를 POST /api/v1/transactions로 제출합니다. SDK는 필요 없습니다. Ed25519, SHA3-256, 제네시스 해시면 충분합니다.

노드는 HTTP 202로 응답합니다. 이는 "끝났음"이 아니라 "받아들였음"을 뜻하며, 트랜잭션의 해시를 돌려줍니다. 그러면 클라이언트는 /api/v1/transactions/<hash>/status를 폴링하며, 상태는 다음과 같이 움직입니다.

  1. 트랜잭션이 블록을 기다리는 동안 staging, 그다음 mempool
  2. 블록이 이를 포함하면 블록 높이와 함께 confirmed
  3. 또는 거부되면 사유와 단계와 함께 rejected. 노드가 이를 모르면 not_found(404)

블록이 15초마다 하나이므로 2초 정도마다 폴링하면 충분합니다. 결제를 받고 상품을 내주기 전에는 확정을, 가능하면 finalized 플래그를 기다리십시오.

응답을 받지 못했다면 똑같은 서명된 바이트를 다시 보내십시오. 해시는 그 바이트로 계산되므로, 이미 그 트랜잭션을 가진 노드는 블록에 이미 포함된 경우라도 중복으로 표시해 다시 202로 응답하며, 트랜잭션은 한 번만 실행됩니다. 새 타임스탬프로 다시 서명하면 다른 트랜잭션이 생기며, 이중 지불은 그렇게 일어납니다.

제출된 트랜잭션의 상태는 staging에서 mempool, confirmed로 움직이거나 rejected가 됩니다. 버전 0.5.8부터는 확정된(confirmed) 트랜잭션에 나중에 finalized 플래그가 붙습니다. 같은 바이트를 다시 보내면 같은 해시가 나오고 한 번만 실행됩니다
제출된 트랜잭션의 상태는 staging에서 mempool, confirmed로 움직이거나 rejected가 됩니다. 버전 0.5.8부터는 확정된(confirmed) 트랜잭션에 나중에 finalized 플래그가 붙습니다. 같은 바이트를 다시 보내면 같은 해시가 나오고 한 번만 실행됩니다

서명된 요청과 취소

몇몇 요청은 자체 서명을 담습니다. METHOD:PATH:TIMESTAMP:BODY에 대한 Ed25519 서명으로, 300초 동안 유효합니다. 5분 안에 서명 인증에 20번 실패한 클라이언트는 300초 동안 차단됩니다. 대기 중인 트랜잭션은 서명된 DELETE 요청으로 한 노드의 풀에서 회수할 수 있습니다(서명된 메시지와 암호화된 메시지).

노드의 그 밖의 인터페이스

  • 포트 8001: 노드 간 P2P 네트워크
  • 포트 8545: MetaMask가 쓰는 Ethereum 방식 JSON-RPC 어댑터. 기본값은 노드 자신의 컴퓨터입니다.
  • 포트 8332: Bitcoin Core 방식 RPC 어댑터. 기본적으로 꺼져 있으며 운영자 자신의 자격 증명이 필요합니다.

같이 보기