개발자 문서

핵심 개념

이 페이지는 에이전트를 통합할 때 다루는 객체와 권위체를 정의합니다. 퀵스타트와 통합 가이드 뒤에 놓인 개념의 척추입니다. 붙들고 가야 할 하나의 발상은 이것입니다. 권위는 어느 한 당사자도 혼자 돈을 움직일 수 없도록 의도적으로 나뉘어 있으며, 아래의 각 객체는 그 분할의 한 조각을 명시적으로 만들기 위해 존재합니다.

에이전트 신원

에이전트는 당신의 개발자 조직과 애플리케이션 클라이언트 아래, 한 환경 안에서 당신의 불투명한 userId와 agentId로 식별됩니다. 그 암호학적 신원은 에이전트 키이며, 그 개인 절반은 오직 당신의 키 저장소에만 있습니다. Tidal은 공개키, 그로부터 유도된 XRPL 계좌, 그리고 단조 증가하는 generation 번호를 기록합니다. 키를 회전하면 generation이 올라가고, 새 키가 결제할 수 있으려면 사용자의 마스터 서명 절차로 그것을 먼저 설치해야 합니다. 회전은 결코 슬그머니 이루어지는 교체가 아닙니다.

두 가지 중요한 성질이 있습니다. 에이전트 키는 정확히 한 가지에만 쓰입니다. 결제에서 에이전트 절반을 서명하는 것입니다. API 요청 서명 키, 웹훅 키, 정책 키로 재사용되는 일이 결코 없습니다. 역할은 의도적으로 분리됩니다. 그리고 Tidal은 에이전트 개인키를 생성하거나 가져오거나 에스크로하거나 백업하거나 운영하지 않습니다. 당신의 키 저장소가 이미 키를 만든 뒤 등록이 시간 초과되더라도, SDK는 재시도 시 새것을 찍어내는 대신 그 같은 키를 재사용합니다.

심부름(예산) 지갑

각 에이전트는 자금이 든 자기 XRPL 계좌 — 예산 계좌 — 를 하나씩 갖습니다. 사용자/앱/에이전트 승인 범위마다 하나입니다. 이것이 심부름 지갑입니다. 사용자 메인 지갑 안의 칸도 아니고 거기에 덧붙인 온체인 지출 한도도 아닌, 실제로 분리된 별개의 계좌입니다. 사용자가 자신의 메인 지갑에서 자금을 넣으며, 그 잔액이 최악의 손실에 대한 확고한, 원장이 강제하는 상한선입니다.

계좌는 정족수 2의 XRPL SignerList로 통제되며, 그 구성원은 에이전트의 키와 Tidal의 공동서명자 키입니다. 사용자의 마스터 키는 활성 상태로 사용자와 함께 남습니다. 일상 결제에는 결코 쓰이지 않지만, 계좌에 자금을 넣고, 서명자 목록을 설치·제거하며, 비상 쓸어 담기를 수행하는 것이 바로 그 키입니다. 예비금과 수수료 완충은 하드코딩이 아니라 라이브 네트워크 값에서 동적으로 계산되며, 결제가 계좌를 예비금 바닥과 수수료 완충 아래로 떨어뜨린다면 fail-closed로 실패합니다.

지출 한도와 정책

사용자의 승인이 정책을 담습니다. 결제당 한도, 하루 한도, 누적 한도, 허용 자산(XRP, RLUSD), 해당하는 경우 허용 수신처나 가맹점, 그리고 만료입니다. 한도를 갱신하면 정책 버전이 그 자리에서 올라갈 뿐, 새 지갑이 필요하지 않습니다.

강제 방식에 대해 정확해야 합니다. 이 한도들은 정책 권위체가 위반 결제를 승인하지 않음으로써 지켜지며, 그 결과 Tidal의 공동서명자가 서명을 보류합니다. 이것은 감사 가능한 서비스 수준의 통제이지 원장 원시 요소가 아닙니다. 원장 자체가 강제하는 것은 딱 두 가지 — 2-of-2 정족수와 계좌 잔액 — 뿐입니다. 그보다 세밀한 모든 것은 정책에 있습니다. 이것이 정직한 경계이며, 보안 모델이 다시 다룹니다.

공동서명과 승인

하나의 자율 결제에는 서로 다른 두 개의 승인이 담기며, 둘을 떼어 놓는 것이 도움이 됩니다.

정책 승인 — 정책·위험 권위체가 호출자를 독립적으로 인증하고, 정규 결제 의도를 스스로 유도하며 (에이전트가 제공한 다이제스트를 신뢰하지 않습니다), 사용자의 승인과 한도에 비추어 검사한 뒤, 결제의 정확한 필드를 묶는 버전화된 승인에 서명합니다. 이것은 원장 서명이 아니라 증거입니다.
XRPL 공동서명 — Tidal의 공동서명자가 그 승인을 검증하고, 최종 거래의 모든 필드를 승인된 의도와 대조하며, 거래 유형이 오직 Payment인지 확인한 뒤에야 HSM/KMS에 든 키에 하나의 XRPL Signer 항목을 만들도록 요청합니다.

에이전트는 자신의 키로 다른 Signer 항목을 만듭니다. 정확히 같은 동결된 거래에 대한 두 개의 서명이 원장에서 정산됩니다. 사용자의 별도 동의 — 승인 그 자체 — 는 그들의 Tidal 지갑을 통해 앞서 확립되며, 결코 당신의 API 키로 뭉뚱그려지지 않습니다.

XRPL에서의 정산

정산은 XRP 원장 위의 평범한 직접 XRP 또는 RLUSD Payment이며, 흔히 x402 요청의 정산 단계로 이루어집니다. 자율 경로는 직접 Payment로 한정되고, 그 밖의 모든 것 — 경로 결제, 부분 결제, DEX/AMM 상호작용, 계좌 관리 거래 — 은 승인을 조회하기도 전에 거부합니다. 범용 거래 서명의 뒷문은 없습니다. RLUSD는 티커만으로가 아니라 네트워크, 발행자, 통화 신원을 함께 대조하므로, 유사 토큰에는 결제할 수 없습니다.

조각들이 어떻게 맞물리는가

flowchart TB
    subgraph dev["당신 쪽"]
        agent["에이전트 런타임"]
        backend["백엔드 + 에이전트 SDK"]
        ks["KeyStore (KMS)<br/>에이전트 개인키"]
    end

    subgraph tidal["Tidal"]
        policy["정책·위험 권위체<br/>승인 · 한도 · 정책 서명"]
        cosigner["공동서명 서비스<br/>HSM/KMS 두 번째 키"]
        walletsvc["지갑 실행<br/>디렉터리 · 멱등성 · 최종성"]
    end

    subgraph user["사용자"]
        client["Tidal 지갑<br/>마스터 키"]
    end

    ledger["XRP 원장<br/>예산 계좌 · SignerList 정족수 2"]

    agent --> backend
    backend <--> ks
    backend -->|"1 결제 제안"| policy
    policy -->|"2 서명된 승인"| walletsvc
    backend -->|"3 에이전트 절반 서명"| ks
    walletsvc -->|"4 승인 시 공동서명"| cosigner
    cosigner -->|"5 두 번째 서명"| walletsvc
    walletsvc -->|"6 조립된 2-of-2"| ledger
    client -->|"자금 · 승인 · 쓸어 담기 가능"| ledger

    classDef d fill:#e8f4ff,stroke:#4a90d9;
    classDef t fill:#e8fff0,stroke:#3aa76d;
    classDef u fill:#fff4e6,stroke:#d98a3a;
    class agent,backend,ks d;
    class policy,cosigner,walletsvc t;
    class client u;

당신 쪽은 에이전트 키를 쥐고 흐름을 구동합니다. Tidal은 정책과 실행과 공동서명을 분리하여 승인, 추적, 두 번째 서명이 서로 다른 책임이 되게 합니다. 사용자는 마스터 키를 소유하고 원장에 직접 닿습니다. 번호가 붙은 간선들이 결제 수명주기이며, 통합 가이드가 단계별로 짚습니다.

초안 — 확정 예정. 정책·위험 권위체와 Tidal의 지갑 실행/공동서명자는 각기 다른 권위 상태를 가진 별개의 서비스입니다. 정확한 배포 토폴로지와 개발자에게 보이는 서비스 명칭은 확정 중입니다. 확정된 불변식은 권위 분할 그 자체입니다. 승인/정책에 하나의 기록자, 지갑 실행과 공동서명에 하나의 기록자, 그리고 에이전트 키는 오직 당신만 쥡니다.