# Tollary — Agent Transaction Guard v3

> AI 에이전트가 Base Mainnet 공식 USDC 전송에 서명하기 직전, 별도의 소유자 또는 HSM 승인을 독립적으로 확인하는 유료 관문입니다. ALLOW 또는 BLOCK을 반환하며 키를 받거나 서명·브로드캐스트·수탁하지 않습니다.

기준 URL: https://tollary.p-e.kr
주력 상품: Agent Transaction Guard
대상: 에이전트가 USDC 거래를 만들지만 격리된 signer는 Guard 경로로만 호출할 수 있게 설계한 팀
메서드와 경로: POST /api/v1/base/usdc/guard
무료 lint: POST /api/v1/base/usdc/guard/lint
OpenAPI 3.1: https://tollary.p-e.kr/openapi.guard.json
현재 결제 메타데이터: https://tollary.p-e.kr/api/product (`product`)
현재 결제 조건 기준: 서명하지 않은 최신 POST가 반환한 PAYMENT-REQUIRED
표시 가격: RPC 상태 기반 ALLOW 또는 BLOCK 정상 판정 1회당 $0.01 USDC
영문 안내: https://tollary.p-e.kr/llms.txt

상업 상태: Mainnet 활성화 상태는 `disabled`입니다. Base Sepolia에서 받는 것은 테스트 토큰일 뿐 실제 USDC, 고객 매출, 수요 증거가 아닙니다. 외부 반복 결제도 아직 검증되지 않았습니다.

## 신뢰 경계

- JSON 최상위는 정확히 `{transaction, mandate}`입니다. 호출자가 `policy`를 넣으면 거부합니다.
- `mandate`는 거래를 만드는 에이전트와 분리된 소유자 승인 흐름, 결정론적 제어 계층, HSM 정책 서비스 등이 EIP-712로 서명한 권한입니다. 같은 비신뢰 에이전트가 거래와 허가를 모두 선택하면 Guard의 권한 경계는 무의미합니다.
- 서버는 검증된 mandate에서만 수취인·금액·유효기간·총 수수료 상한 정책을 파생합니다.
- 서명 복구는 어느 주소가 서명했는지만 증명합니다. 그 주소가 정당한 소유자인지는 증명하지 않습니다. `message.issuer`를 별도의 인증 경로에서 `expectedIssuer`로 고정합니다.
- HTTPS audience도 별도로 고정합니다. `message.audience`와 EIP-712 domain salt는 `keccak256("https://tollary.p-e.kr/api/v1/base/usdc/guard")`입니다. 에이전트나 검사 대상 응답에서 신뢰 기준을 가져오지 않습니다.
- `message.nonce`는 한 번만 쓸 수 있습니다. 유료 경로는 결제 전에 nonce를 영속 예약하며 재사용·충돌을 거부합니다. 무료 lint는 서명을 검증하지만 nonce를 예약하지 않습니다.
- 키 자료, 시드 문구, 서명된 거래, x402 결제 승인, 세션 비밀값을 절대 제출하지 않습니다. Guard는 지갑 연결, 서명, 브로드캐스트, 전송, 자산 보관·복구를 하지 않습니다.
- ALLOW는 짧은 시간 동안의 상태 증거일 뿐 수취인 신원 확인, 투자 의견, 정산 보증이 아닙니다.

## 정확한 요청 계약

최상위에는 `transaction`과 `mandate`만 있고 추가 필드는 없습니다.

`transaction`에는 다음 필드만 정확히 포함합니다.

- `type`: `"0x2"`
- `chainId`: 정수 `8453`
- `from`: 표준 소문자 송신자 주소
- `to`: Base Mainnet 공식 USDC `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`
- `data`: 정확히 한 번의 `transfer(address,uint256)`에 대한 표준 소문자 ABI data
- `value`: 10진 문자열 `"0"`
- `nonce`: 송신자의 정확한 표준 10진 nonce
- `gasLimit`: 양의 표준 10진 문자열
- `maxFeePerGasWei`: 표준 10진 문자열
- `maxPriorityFeePerGasWei`: 표준 10진 문자열
- `accessList`: 빈 배열

`mandate`에는 `message`와 `signature`만 있습니다. `message`에는 다음 필드만 정확히 포함합니다.

- `issuer`, `sender`, `token`, `recipient`
- `amountAtomic`
- `unsignedTxDigest`
- `maxTotalFeeWei`
- `notBefore`, `validUntil`
- `nonce`
- `audience`

서명은 `r`이 0이 아니고 low-`s`이며 `v`가 `1b` 또는 `1c`인 표준 소문자 65바이트 secp256k1 EIP-712 값입니다. `notBefore`부터 `validUntil`까지 서명 유효기간은 최대 5분입니다. 매번 새 mandate를 만들고 서명합니다. 예제의 시각·nonce·audience·digest·서명을 복사하지 않습니다.

## 무료 lint와 유료 상태 관문

1. 새 정확한 요청을 `/api/v1/base/usdc/guard/lint`에 POST합니다. mandate와 구조를 비동기로 검증하지만 RPC를 사용하지 않고 nonce도 예약하지 않으며 결제도 요청하지 않습니다.
2. 구조적 BLOCK은 무료입니다. lint ALLOW는 같은 서명 요청을 유료 상태 관문에 보낼 수 있다는 뜻일 뿐입니다.
3. 그 정확한 요청을 PAYMENT-SIGNATURE 없이 `/api/v1/base/usdc/guard`에 POST합니다. 이 요청만으로는 결제가 정산되지 않습니다.
4. 400이면 잘못됐거나 구조적으로 차단된 요청을 다시 만듭니다. 409이면 새 mandate nonce와 거래 digest를 만듭니다. 503이면 중단합니다. 결제는 요청되지 않습니다.
5. 402면 최신 PAYMENT-REQUIRED를 해석합니다. scheme, network, asset, 원자 단위 금액, payTo, timeout, extensions, 현재 `payment.livePayments`, 구매자 지출 정책을 모두 확인합니다. 정적 문서는 결제를 승인하지 않습니다.
6. 외부 구매자 구현만 PAYMENT-SIGNATURE 첨부를 결정할 수 있습니다. 실제 구매 전에는 현재 메타데이터에서 Mainnet 활성화를 명시적으로 확인해야 합니다.

## 유료 결과가 증명하는 것

`base-usdc-guard-rpc-v3` 응답은 정확히 두 독립 RPC 운영자의 관측을 두 층으로 나눕니다.

- `canonicalSafe`: 두 운영자가 독립적으로 합의한 safe block의 안정적인 감사 증거입니다.
- `executionRecent`: 서명 직전 sender nonce, 참고용 pending nonce, 잔액, 공식 USDC 상태, 시뮬레이션, gas, 수수료를 검사하는 최신 실행 상태입니다.

`verification.signBy`는 검증 후 최대 10초이며 mandate 만료보다 늦을 수 없는 강제 마감입니다. 서명과 브로드캐스트를 모두 그 전에 끝내야 합니다. 영수증 복구로 `signBy`가 연장되지 않습니다.

구조적 BLOCK은 무료이고 RPC 상태에서 나온 ALLOW 또는 BLOCK은 정상 유료 결과입니다. 네트워크 불일치나 증거 부재는 서비스 실패이며 권위 있는 판정이 아닙니다.

## Attestation과 서명 바이트 강제

- 별도 인증 경로에서 고정한 공개 descriptor로 `agent-transaction-guard-attestation` 헤더의 `guardId` 대상 Ed25519 서명을 검증합니다.
- PAYMENT-RESPONSE는 따로 검증합니다. 이것은 x402 정산 증거이지 Guard 보안 attestation이 아닙니다.
- `https://tollary.p-e.kr/sdk/guarded-viem-3.0.0.mjs`의 고정 버전 Node ESM SDK를 내려받고 `https://tollary.p-e.kr/sdk/guarded-viem.manifest.json`의 무결성 값과 대조합니다. 고정한 `expectedIssuer`를 요구하고, 전체 proof와 Ed25519 attestation을 검증하고, 서명 직전에 후보 unsigned transaction을 Guard 거래와 비교합니다. signer가 반환한 EIP-1559 바이트를 다시 해석하고 송신자를 복구한 뒤 모든 필드를 재비교하고 브로드캐스트합니다.
- `https://tollary.p-e.kr/sdk/guard-client-1.0.0.mjs`의 단일 Node x402 어댑터를 `https://tollary.p-e.kr/sdk/guard-client.manifest.json`에 고정해 정확한 요청을 검사하거나 구매합니다. 기본값은 Base Sepolia이고, raw key 대신 호출자 소유 결제 서명 콜백을 받으며, fetch 전에 durable 복구 저장을 요구하고, exported identity token 없이는 Mainnet을 선택하지 않습니다.
- AWS KMS `ECC_SECG_P256K1` 팀은 `https://tollary.p-e.kr/sdk/aws-kms-fit-check-1.0.0.mjs`의 무네트워크 검사를 먼저 실행한 뒤 `https://tollary.p-e.kr/sdk/aws-kms-guard-gateway-1.0.0.mjs`를 사용할 수 있습니다. 둘 다 `https://tollary.p-e.kr/sdk/aws-kms-guard-gateway.manifest.json`에 고정합니다. 에이전트 role에는 `kms:Sign`을 명시적으로 거부하고, 분리된 gateway role만 proof 검증 뒤 정확한 digest 한 건을 서명할 수 있어야 합니다.
- 에이전트가 raw signer, 제한 없는 wallet 메서드, 다른 relay 또는 broadcast 경로로 우회할 수 있으면 SDK는 강제력이 없습니다.

## 영수증 및 거래 주기 복구

- 유료 응답 유실: GET `/api/v1/base/usdc/guard/receipts/{paymentIdentifier}`. URL 안의 식별자 자체가 bearer 복구 비밀값입니다.
- 정산 주기: GET 또는 POST `/api/v1/base/usdc/guard/receipts/{paymentIdentifier}/settlement`와 `Authorization: Bearer {paymentIdentifier}`를 사용합니다.
- 정산 POST body는 정확히 `{transactionHash, requestedFinality}`이며 finality는 `included`, `safe`, `finalized` 중 하나입니다.
- payment identifier, 복구 URL, Authorization 값, 결제 서명, 정산 자료가 든 응답 헤더를 공개하거나 로그에 남기지 않습니다.

## 기계용 인터페이스

- Guard OpenAPI: https://tollary.p-e.kr/openapi.guard.json
- 현재 상품 메타데이터: https://tollary.p-e.kr/api/product
- Guard 엔드포인트: https://tollary.p-e.kr/api/v1/base/usdc/guard
- Guard 검증 프로필: https://tollary.p-e.kr/proof-verification.json
- Guard 구매 클라이언트: https://tollary.p-e.kr/sdk/guard-client-1.0.0.mjs
- Guard 구매 안내: https://tollary.p-e.kr/sdk/guard-client-README.md
- AWS KMS 게이트웨이: https://tollary.p-e.kr/sdk/aws-kms-guard-gateway-1.0.0.mjs
- AWS KMS 오프라인 fit-check: https://tollary.p-e.kr/sdk/aws-kms-fit-check-1.0.0.mjs
- AWS KMS 통합 안내: https://tollary.p-e.kr/sdk/aws-kms-guard-gateway-README.md
- 발견 manifest: https://tollary.p-e.kr/.well-known/proof-of-utility.json
- 집계 결제 지표: https://tollary.p-e.kr/api/commerce
- 서비스 상태: https://tollary.p-e.kr/api/health
- Guard 준비 상태: https://tollary.p-e.kr/api/readiness
- 상업·법적 고지: https://tollary.p-e.kr/api/legal
- x402 Bazaar 검색: https://api.cdp.coinbase.com/platform/v2/x402/discovery/search

기존 Ethereum 소각 Proof는 무료 기술 데모이며 이 상품도, 검증된 매출도 아닙니다.