Update HPP Router documentation to reflect x402 wallet integration an… - #21
Conversation
hayarobi
left a comment
hayarobi
left a comment
There was a problem hiding this comment.
It appears that the term "quota" is no longer used, but the "quota & usage" title still appears on the left sidebar. Is this section being maintained as is?
dohoon84
left a comment
dohoon84
left a comment
There was a problem hiding this comment.
hpp-router 리포지토리(소스 코드, Kong 설정, SDK, docs 내 x402 섹션)와 대조하여 리뷰했습니다. 전반적으로 x402 지갑 결제(온체인 USDC.e) 반영 취지는 좋으나, 실제 구현과 어긋나는 부분이 여러 군데 있어 우선 문서/코드를 서로 맞추는 작업이 필요해 보입니다. 상세 코멘트는 각 라인에 남겼고, 아래는 파일 간에 공통으로 반복되는 이슈를 모아 정리한 것입니다.
1) 결제 레일 헤더명이 문서 전체에서 틀려 있습니다 (가장 중요)
authentication.mdx, quickstart.mdx, guides/chat-completions.mdx, guides/image-generation.mdx, guides/streaming.mdx, guides/vision-multimodal.mdx, api-reference/consumer-api.md, intro.md 전체에서 X-HPP-Payment-Rail: wallet 헤더를 쓰도록 안내하고 있는데, 실제 hpp-router 소스에서는 X-Payment-Rail: wallet 헤더를 사용합니다.
- 근거:
src/x402-config.js(isWalletPaymentRail이req.headers['x-payment-rail']를 읨),kong-plugins/kong/plugins/noosphere-router/handler.lua:235,kong/kong.yaml:593(CORS allow-list),client/src/lib/wallet/x402PaymentRequest.ts:109,client/src/lib/chat/streamChatCompletion.ts:178. X-HPP-Payment-Rail이라는 문자열은 hpp-router 코드베이스 어디에도 없습니다. 문서 그대로 호출하면 지갑 결제 레일이 인식되지 않을 것으로 보입니다. 전체 파일 일괄 수정이 필요합니다.
2) USDC → USDC.e
온체인 정산 토큰은 USDC.e(Bridged USDC, 0x401eCb1D350407f13ba348573E5630B83638E30D, src/x402-config.js의 USDC_E_ADDRESS)입니다. 이 저장소의 x402/intro.md, x402/networks-and-token.mdx도 이미 "USDC.e"로 일관되게 표기하고 있습니다. 이번 PR에서 "USDC"로만 표기된 부분(authentication.mdx, quickstart.mdx, models-and-pricing.mdx, guides/quota-and-usage.mdx, intro.md 등)을 "USDC.e"로 통일해 주세요. (검토자 지적사항)
3) API 키 발급 경로 — HPP 포털도 함께 명시 필요
authentication.mdx의 "Getting an API key"(diff 범위 밖이라 인라인 코멘트를 남기지 못했습니다, 16행: "API keys are issued through HPP Hub, the HPP developer portal.")와 intro.md 40행, quickstart.mdx 16행 모두 API 키 발급처를 HPP Hub로만 안내합니다. hpp-router 소스 확인 결과 API 키는 자체 포털(POST /api/user/keys, src/user-api.js)에서도 발급 가능하고, HPP Hub·admin·partner 경로로도 발급됩니다. "HPP Hub에서만 발급"으로 오독될 수 있는 현재 문구를 "HPP 포털에서 발급 가능하며, 추가로 HPP Hub를 통해서도 발급 가능"으로 보완해 주세요. (검토자 지적사항과 일치)
4) x402 프로토콜 링크
authentication.mdx 78행의 https://docs.x402.com 링크는 (a) 도메인이 실제 x402 재단 공식 문서 도메인(docs.x402.org)과 다르고, (b) 이 docs 저장소에 이미 HPP 전용 x402 문서 섹션(/x402, x402/intro.md 등)이 있으므로 외부 링크 대신 그쪽으로 연결하는 것이 맞아 보입니다. (검토자 지적사항)
5) GET /llm/v1/models 인증 필요 여부
models-and-pricing.mdx, authentication.mdx, consumer-api.md, consumer-v1.yaml, client-sdk/typescript.mdx에서 일괄적으로 "API 키 불필요"로 바뀌었는데, hpp-router의 kong/kong.yaml을 보면 /llm/v1/models 라우트에는 key-auth 플러그인이 적용되어 있어 Kong을 통한 실제 호출에는 API 키가 필요한 것으로 보입니다. 인증이 필요 없는 것은 별도 엔드포인트인 GET /public/v1/models(src/public-router.js)입니다. 실제로 라우팅이 무인증으로 바뀐 것이 맞는지 백엔드 쪽 확인 후 반영 부탁드립니다. (검토자 지적사항과 일치)
6) /api/quota-check 엔드포인트를 문서에서 삭제했는데 실제로는 존재
authentication.mdx, consumer-api.md의 엔드포인트 표에서 GET /api/quota-check가 삭제되고 GET /api/user/audit/:logId로 대체되었는데, hpp-router 소스(src/dashboard.js, kong/kong.yaml의 public allowlist ~/api/(usage|quota-check|pricing|info|audit)$)를 보면 /api/quota-check는 제거되지 않았습니다. 두 엔드포인트는 대체 관계가 아니라 둘 다 살아있으므로, 표에서 삭제하지 말고 /api/user/audit/:logId를 추가하는 형태로 수정해야 합니다. consumer-v1.yaml에는 애초에 /api/quota-check path가 그대로 남아있어 markdown과 yaml 간 불일치도 발생합니다.
7) /api/usage 응답 스키마 — 문서 간 불일치
guides/quota-and-usage.mdx는 응답 예시를 spent_usdc_micro/settle_success_count/settle_failed_count로 교체했지만, consumer-api.md의 UsageResponse 설명은 이 필드들을 언급하지 않고 quota/used/remaining만 제거했습니다. consumer-v1.yaml의 UsageResponse 스키마(397행~)는 여전히 quota/used/remaining을 required로 선언하고 있어 세 문서가 서로 다른 내용을 말하고 있습니다. 실제로는 ?rail=wallet 쿼리 파라미터가 있을 때만 정산 필드가 추가되고 기본 응답에는 quota 필드가 남는 것으로 보이니, 이 동작을 명확히 설명하고 세 문서를 통일해 주세요.
각 파일 상세 코멘트는 라인별로 남겼습니다. 확인 후 반영 부탁드립니다.
…d on-chain USDC payments. Key changes include: - Revised authentication requirements to include x402 wallet payments. - Updated API endpoints and examples to demonstrate wallet payment integration. - Enhanced descriptions of usage tracking and billing processes. - Clarified error handling for insufficient funds and payment requirements. - Adjusted sections on models and pricing to align with new billing methods. These updates ensure comprehensive guidance for users on utilizing the new payment system effectively.
- Included 'ollama/solidity-master:2' in the list of available models. This update enhances the API reference documentation for users integrating with the HPP Router.
… and API key issuance - Clarified that API keys can be issued from both the HPP Router portal and HPP Hub. - Updated references to on-chain payments, specifying USDC.e instead of USDC. - Revised headers for wallet payments to use `X-Payment-Rail` instead of `X-HPP-Payment-Rail`. - Enhanced documentation on usage tracking, billing processes, and error handling related to wallet payments. - Adjusted sections on quota and usage to include details on prepaid quota alongside wallet settlement.
1ce53b4 to
087afd7
Compare
… listing endpoint. Removed redundant mention of a separate public models route, streamlining the information for better clarity.
|
@dohoon84 내용부분은 제가 완전히 파악하기 어려워서요. 내용 부분에서는 도훈씨가 검토하여 승인을 하시면 PR승인처리를 진행하겠습니다. |
…'usage-and-settlement' across multiple files. This includes updates to sidebar configuration, API references, and guides to ensure consistency and clarity regarding usage tracking and billing processes.
3 participants
…d on-chain USDC payments. Key changes include:
These updates ensure comprehensive guidance for users on utilizing the new payment system effectively.