Label 309 게이트웨이 위에 제품을 구축하는 방법

블록체인을 직접 운영하지 않고 존재 증명 기능을 구축하려면, 게이트웨이 위에 구축합니다. Label 309 게이트웨이는 존재 증명 제품 뒤에 있는 게시 엔진입니다. 견적, 업로드, Cardano 트랜잭션 제출, 확인, 리오그(reorg) 처리, 레코드 인덱싱, 계정 잔액, 스토리지 자금 조달, API 키, 웹훅 같은 까다로운 운영 작업을 모두 처리하고, 이를 전부 평범한 HTTP로 노출합니다. 여러분의 제품은 이러한 엔드포인트를 호출하고, 사용자가 실제로 보는 모든 것 — 인터페이스, 결제 관계, 도메인 워크플로, 브랜드 — 을 책임집니다.

게이트웨이 코어는 오픈 소스이며, CardanoWall은 그 위에 구축된 레퍼런스 제품입니다. 개발자에게 유용한 점은 별도의 비공개 통로가 없다는 것입니다. CardanoWall은 여러분이 사용하는 것과 동일한 공개 엔드포인트를 통해 게이트웨이에 접근하므로, 레퍼런스 제품에서 동작하는 패턴은 여러분에게도 동일하게 동작합니다.

누가 게이트웨이 위에 구축해야 합니까?

존재 증명을 웹사이트에서 사용자가 수동으로 수행하는 동작이 아니라 제품 내부에 두고 싶다면, 게이트웨이 위에 구축하십시오.

적합한 사례는 다음과 같습니다.

• 문서 공증 제품;
• 컴플라이언스 증거 아카이브;
• AI 출처 증명 및 데이터셋 거버넌스 플랫폼;
• 지속적 통합 증명 시스템;
• 법적 증거 도구;
• 암호화된 정보 공개 포털;
• 미디어 진위 확인 서비스;
• 내부 엔터프라이즈 감사 도구;
• 퍼블리셔 증명 페이지.

이 모든 경우에서 사용자는 Cardano 트랜잭션 구성, UTxO 자금 조달, 스토리지 크레딧, 체인 확인을 신경 쓰고 싶어 하지 않습니다. 사용자가 원하는 것은 내구성 있고 검증 가능한 증명을 만들어 내는 워크플로입니다. 게이트웨이는 여러분의 팀이 Cardano 인프라 운영자가 되지 않고도 그 워크플로를 가능하게 합니다.

게이트웨이는 무엇을 책임지고, 여러분의 제품은 무엇을 책임집니까?

이 분담이 핵심이므로 분명하게 짚어 둘 가치가 있습니다. 게이트웨이는 베이스 플레인 — 게시 파이프라인과 그 뒤에 있는 모든 자금·체인·스토리지 상태 — 을 책임집니다.

• 견적, 업로드, 게시;
• Cardano 트랜잭션 빌드, 제출, 확인, 리오그 처리, 영구 실패 시 환불;
• 콘텐츠와 암호문의 스토리지 업로드, 그리고 그 뒤의 스토리지 자금 조달;
• 네트워크상의 모든 Label 309 레코드를 포괄하는 공유 온체인 레코드 인덱스;
• 계정 잔액과 그것을 변동시키는 원장 항목;
• 외환 가격 책정과 마진;
• API 자격 증명과 웹훅 전달.

이는 인프라 작업입니다. 운영 환경에서는 정밀하고, 관측 가능하며, 지루할 만큼 안정적이어야 합니다. 게이트웨이를 운영하는 것이 여러분의 실제 업무가 아닌 한, 애플리케이션이 이를 다시 구현해서는 안 됩니다. 만약 그것이 실제 업무라면 직접 게이트웨이를 운영하기를 참고하십시오.

여러분의 제품은 벤더 플레인 — 벤더 측에 해당하는 모든 것 — 을 책임집니다.

• 사용자 계정과 세션;
• 온보딩과 결제;
• 제품 권한;
• 여러분의 인터페이스와 이메일;
• 고객에게 제시하는 가격;
• "사건", "릴리스", "데이터셋", "증거 패키지" 같은 도메인 개념;
• 게이트웨이 이벤트로 구성한 읽기 모델;
• 지원 워크플로.

게이트웨이는 어떤 증명이 소송, 모델 학습 실행, 분기별 컴플라이언스 패키지, 잡지 호에 속하는지 알 필요가 없습니다. 게이트웨이는 올바른 Label 309 레코드를 게시하고 그 주변의 운영 상태를 유지하기만 하면 됩니다. 이 분리는 두 시스템을 모두 더 깔끔하게 유지합니다. 여러분의 제품은 체인이나 자금 상태를 건드리지 않고도 재구축하거나 리브랜딩할 수 있고, 게이트웨이는 여러분의 제품이 존재한다는 사실을 모른 채 업그레이드할 수 있습니다.

사용자를 대신해 데이터 플레인을 어떻게 호출합니까?

데이터 플레인(/api/v1/*)은 계정을 대상으로 하는 API입니다. 동작이 사용자나 계정을 대신해 일어날 때는 언제든 이것을 사용하십시오.

• 게시 견적 요청;
• 콘텐츠나 암호문 업로드;
• 레코드 게시;
• 잔액 또는 계정 원장 조회;
• 공개 레코드 목록 조회, 가져오기, 검증;
• 계정 범위 웹훅 등록.

래퍼 제품에서는 여러분의 백엔드가 사용자의 게이트웨이 계정에 대해 수명이 짧은 계정 토큰을 발급하고, 클라이언트는 필요한 스코프만으로 데이터 플레인을 호출합니다. 스코프가 권한 경계입니다. 게시 화면에는 poe:create가 필요하고, 잔액 위젯에는 account:read가 필요하며, 공개 레코드 엔드포인트에는 자격 증명이 전혀 필요하지 않습니다. 이 엔드포인트는 익명 호출자에게 서비스되며, 바로 이 점이 인덱스를 고객별 뷰가 아닌 공공재로 만듭니다.

토큰은 설계상 수명이 짧습니다(기본값은 1시간). 세션마다 하나씩 발급하고 만료 시 다시 발급하면, 토큰이 유출되더라도 1시간짜리 문제에 그치고 사고로 번지지 않습니다. 그리고 운영자 자격 증명을 절대 브라우저로 보내지 마십시오. 다음 섹션은 바로 이 한 가지 규칙을 지키기 위해 존재합니다.

운영자로서 컨트롤 플레인을 어떻게 호출합니까?

컨트롤 플레인(/control/v1/*)은 신뢰된 백엔드와 운영자만을 위한 것입니다. 다음 용도로 사용하십시오.

• 게이트웨이 계정 생성 및 활성화·비활성화;
• 결제 시스템이 자금을 수금한 후 원장 조정 적용;
• 계정별 마진 설정;
• 계정 토큰과 API 키 발급;
• 운영자 웹훅 파이어호스 등록;
• 지갑과 스토리지 자금원 등록 및 관리;
• 감사 및 운영 상태 조회.

이 플레인은 여러분의 백엔드 뒤에 자리합니다. 운영자 자격 증명은 지출 권한이 있는 운영 환경 비밀처럼 다루십시오 — 실제로 그 권한을 가지고 있기 때문입니다. 수명이 짧은 운영자 토큰(기본값 24시간)은 일상적인 관리를 처리합니다. 비밀 저장소에 보관하는 단일 루트 비밀은 지갑과 스토리지 자금원을 등록하는 몇 가지 작업에만 한정해 둡니다.

컨트롤 플레인은 여러분의 결제 시스템과 게이트웨이의 선불 잔액이 연결된 상태를 유지하는 방법입니다. 여러분의 시스템에서 결제가 성공하면, 백엔드가 게이트웨이 계정에 멱등한 원장 조정을 한 번 적용합니다. 이것이 크레딧 레일의 전부이며, 이어지는 두 섹션에서 그것이 정확히 왜 이렇게 설계되었는지 설명합니다.

게이트웨이의 테이블을 직접 쿼리하면 안 되는 이유는 무엇입니까?

스키마는 계약이 아니기 때문입니다 — 계약은 HTTP API와 웹훅입니다.

게이트웨이 엔진은 자체 Postgres 스키마(cw_core와 cw_api)를 소유합니다. 두 시스템이 동일한 Postgres 인스턴스를 공유하더라도, 여러분의 제품은 이 스키마를 읽거나 써서는 안 됩니다. 스키마 공존은 지원되는 배포 형태이지만, 경계는 데이터베이스가 아니라 스키마입니다. 그 엔진 스키마는 내부용이며 예고 없이 바뀔 수 있는 반면, HTTP 플레인과 파이어호스는 안정적입니다. 이 경계를 넘어 접근하면, 일상적인 게이트웨이 업그레이드가 여러분의 제품을 조용히 망가뜨릴 수 있습니다.

API가 노출하지 않는 데이터가 필요하다면, 이를 스키마를 가로질러 조인해도 된다는 허가가 아니라 제기해야 할 API 공백으로 다루십시오.

게이트웨이 이벤트로 자체 화면을 어떻게 구축합니까?

모든 제품에는 자체 뷰가 필요합니다. 보낸 레코드, 고객 이력, 잔액, 게시 실패, 사건 타임라인, 증거 패키지, 감사 대시보드가 그렇습니다. 이를 모든 행을 폴링하거나 게이트웨이 내부에 조인해서 구축하지 마십시오.

대신 웹훅을 등록하고 이벤트를 여러분 자신의 테이블에 투영하십시오. 게이트웨이는 운영자 파이어호스(인스턴스의 모든 라이프사이클 이벤트)와, 더 좁은 워크플로를 위한 계정 범위 웹훅 구독을 노출합니다. "보낸 항목" 뷰가 대표적인 예입니다. 게시 상태 이벤트를 소비해 자신의 테이블에 투영하고, 거기에서 렌더링하십시오.

전달은 최소 한 번(at-least-once) 방식이므로, 투영을 멱등하게 만드십시오. 실용적인 읽기 모델은 다음을 키로 삼을 수 있습니다.

• 이벤트 id 또는 전달 id (재전달이 무동작이 되도록);
• 게이트웨이의 레코드 id;
• 최종 트랜잭션 해시;
• 여러분 자신의 사용자 id;
• 여러분 자신의 도메인 객체 id;
• 상태와 타임스탬프.

그러면 여러분의 인터페이스는 자신의 테이블에서 렌더링하고, 게이트웨이는 지출, 게시 라이프사이클, 체인 사실에 대한 권위로 남습니다. 각 전달은 서명됩니다. 이벤트를 신뢰하기 전에 서명을 검증하고 타임스탬프 허용 오차 창을 적용하십시오.

자금이 결제 시스템과 게이트웨이 사이에서 어떻게 흘러야 합니까?

모델을 단순하게 유지하십시오. 게이트웨이 잔액이 지출 가능한 잔액이며, 여러분의 결제 시스템은 그 잔액에 자금을 도달시키는 한 가지 경로일 뿐입니다.

여러분의 결제 레일은 카드, 청구서, 암호화폐 결제, 수동 엔터프라이즈 크레딧, 또는 보조금을 수금할 수 있습니다. 게이트웨이는 그중 어떤 것도 알 필요가 없습니다. 깔끔한 패턴은 다음과 같습니다.

1. 여러분의 결제 시스템이 결제를 확인합니다.
2. 백엔드가 결제 id를 키로 삼아 게이트웨이 계정에 멱등한 원장 조정을 한 번 적용합니다.
3. 게이트웨이 잔액이 증가합니다.
4. 이후의 게시 및 업로드 작업이 그 잔액에서 차감됩니다.
5. 게시가 영구적으로 실패하면, 게이트웨이가 차감을 스스로 되돌립니다.

여기서 두 가지 결론이 따라옵니다. 첫째, 결제 파이프라인은 최소 한 번 방식으로 전달하므로 멱등성이 중요합니다. 결제 자체의 id를 조정 참조로 전달하면, 한 결제가 다섯 번 전달되더라도 잔액에는 한 번만 크레딧됩니다. 둘째, 게이트웨이 원장을 자신의 테이블에 복제하고 그 복제본을 지출 결정의 진실로 취급하지 마십시오 — 필요하다면 렌더링용으로 캐시하되, 결정이 실제로 자금을 움직일 때는 언제나 게이트웨이를 읽으십시오. 게이트웨이가 자체적으로 환불을 발행하므로, 게시 실패에 대한 벤더 측 환불 경로도 만들지 말아야 합니다. 그렇게 하면 이중 환불이 발생합니다.

각 종류의 키는 어디에 두어야 합니까?

게이트웨이는 사용자의 신원 시드(Identity Seed)를 결코 필요로 해서는 안 됩니다. 클라이언트나 SDK가 로컬에서 콘텐츠를 해시하고, 봉인된 페이로드를 암호화하고, 레코드에 서명할 수 있습니다. 게이트웨이는 완성된 레코드 바이트를 게시하고 Cardano 트랜잭션을 제출하기만 합니다. (이 경계가 처음부터 끝까지 왜 중요한지는 키가 기기를 떠나지 않는 이유를 참고하십시오.)

완전한 통합에는 여러 가지 별개의 키 부류가 있으며, 피해야 할 실수는 이들을 하나의 "API 비밀"로 뭉뚱그리는 것입니다. 이들은 영향 반경이 매우 다릅니다.

• 사용자 신원 시드와 수신자 개인 키 — 사용자의 암호학적 신원으로, 엣지에 속합니다;
• 그 신원에서 파생된 레코드 서명 키;
• 계정 API 키와 수명이 짧은 계정 토큰 — 그것을 필요로 하는 제품 또는 클라이언트 컨텍스트에 속합니다;
• 운영자 토큰과 루트 비밀 — 신뢰된 백엔드에만 속합니다;
• 게이트웨이 자체의 Cardano 및 스토리지 서명 키와 웹훅 서명 비밀 — 게이트웨이 키링에 속합니다.

각 부류를 그것을 담을 수 있는 가장 작은 장소에 대응시키면, 단 한 번의 유출도 그 안에 갇힙니다.

호스팅된 게이트웨이 대신 게이트웨이를 직접 호스팅해야 하는 경우는 언제입니까?

편의보다 운영 독립성이 더 중요할 때 직접 호스팅하십시오.

호스팅된 게이트웨이는 대부분의 통합에서 가장 간단한 경로입니다. 표준 API 표면을 통해 준비된 서비스로 게시하고, 체인이나 스토리지 운영을 직접 하지 않습니다. 직접 호스팅은 그 간단함을 제어권과 맞바꿉니다 — 자신의 Cardano 지갑 자금 조달, 자신의 스토리지 자금 조달, 자신의 운영자 정책, 자신의 가동 시간과 네트워크 의존성, 자신의 마진, 자신의 컴플라이언스 경계, 그리고 게시를 위해 제3자에게 의존하지 않는 것입니다.

하지만 제어권은 곧 책임이기도 합니다. 직접 호스팅한다는 것은 ADA와 스토리지 크레딧에 자금을 대고, 키링을 보호하고, Postgres를 운영하고, 체인 공급자를 모니터링하고, 백업을 처리하고, 자격 증명을 교체하고, 웹훅을 관리하고, 사고에 대응한다는 뜻입니다. 직접 호스팅은 벤더 의존성을 제거하지만, 운영 작업을 제거하지는 않습니다. 직접 게이트웨이를 운영하기에서 이것이 실제로 무엇을 수반하는지 짚어 봅니다.

사용자는 증명에서 무엇을 보아야 합니까?

대부분의 사용자는 여러분의 제품 개념을 먼저 보아야 합니다. 그들이 신경 쓰는 것은 "증거 게시", "이 파일 봉인", "이 데이터셋 스냅숏 증명", 또는 "이 릴리스 고정"입니다. 제품을 사용하기 위해 메타데이터 명세를 읽어야 해서는 안 됩니다.

그렇더라도 모든 증명 뷰는 그 클레임을 독립적으로 확인할 수 있게 만드는 사실들을 노출해야 합니다.

• 트랜잭션 해시;
• 블록 타임과 확인 상태;
• 해시 알고리즘과 다이제스트;
• 레코드가 서명된 경우, 서명자의 공개 키;
• 존재하는 경우, 스토리지 URI;
• 해당되는 경우, 봉인 수신자 상태;
• 레코드가 여러 파일을 배칭하는 경우, Merkle 루트와 리프 증명;
• 검증 판정 그 자체.

이렇게 해야 제품은 그 밑에 깔린 암호학적 클레임을 숨기지 않으면서도 쾌적하게 사용할 수 있는 상태를 유지합니다.

제품을 하나의 게이트웨이에 묶이지 않게 하려면 어떻게 합니까?

게이트웨이는 게시를 돕습니다. 게이트웨이가 증명 그 자체가 되어서는 결코 안 됩니다.

체인상의 레코드는 Label 309 메타데이터이며, 검증은 오직 세 가지 입력 — 트랜잭션 메타데이터, 선택적으로 콘텐츠 바이트, 그리고 공개 Cardano 익스플로러 — 만으로 동작하도록 설계되었습니다. 봉인된 레코드를 복호화할 때만 수신자 키가 추가됩니다. 그 신뢰 경로에는 어떤 발행자 서버도 끼어들지 않습니다. 여러분의 게이트웨이가 내일 사라지더라도, 유효한 레코드는 독립적인 도구로 여전히 검증되어야 합니다. 또한 그러한 증명이 무엇을 단언하고 무엇을 단언하지 않는지 기억해 둘 가치가 있습니다. 그것은 정확한 바이트가 공개적으로 확인 가능한 시점에 존재했음을 보여 줄 뿐, 그 바이트에 관한 어떤 주장이 참이거나, 소유되었거나, 승인되었음을 보여 주지는 않습니다.

여러분의 제품을 그 약속을 중심으로 구축하십시오.

• 트랜잭션 해시를 내구성 있게 저장하십시오;
• 사용자가 검증 보고서를 내보내고 증거 패키지를 다운로드할 수 있게 하십시오;
• Merkle 리프 목록과 그 증명을 보관하십시오;
• 여러분의 인터페이스 밖에서 레코드를 검증하는 방법을 문서화하십시오;
• 여러분의 백엔드만 해석할 수 있는 비공개 필드를 피하십시오.

이것이 "우리에게 데이터베이스 행이 있다"와 "우리는 누구나 확인할 수 있는 증명을 만들어 냈다"의 차이입니다.

더 읽어 보기

• Label 309 게이트웨이란 무엇입니까?와 직접 게이트웨이를 운영하기 — 운영자 관점에서 본 게이트웨이.
• CardanoWall API 위에 구축하기와 자동화에서 CLI 사용하기 — 개발자 대상 표면을 더 자세히.
• 게시에 비용이 드는 이유 — 선불 잔액이 실제로 무엇에 지불되는가.
• Label 309는 오픈 소스입니다 — 표준과 그 레퍼런스 코드.
• 오픈 소스 표준은 label309.org에 있으며, 게이트웨이, SDK, CLI는 github.com/cardanowall에 있습니다. Label 309는 Cardano CIP 프로세스에 제출되었으며, Metadata 범주 제안으로 CIP 편집자들의 검토를 받고 있습니다.