v2 북극성v2 north star
Settlement OS + px402 + PayFiSettlement OS + px402 + PayFi
PayChain
Financial Settlement & Execution · v1.5 커널 · v2 px402 로드맵Financial settlement & execution · v1.5 kernel · v2 px402 roadmap
스테이블코인, 은행, PG, 웹3 — 레일이 달라도 같은 운영 흐름으로 맞출 수 있습니다.Stablecoins, banks, PGs, Web3 — different rails, one operating flow.
여러 파트너와 레일을 붙여도
결제 처리, 정산 확인, 감사 대응을
하나의 흐름으로 운영할 수 있게 만듭니다.
Connect many partners and rails,
yet keep payment operations, settlement confirmation, and audit response
in one consistent operating flow.
소비자용 결제 앱이나 지갑이 아닙니다. 자산을 보관하거나 환전해 드리지 않습니다.
기관·파트너가 쓰는 결제·정산 운영 허브입니다.
Not a consumer wallet or checkout app. We don’t hold assets or handle FX.
A payments and settlement hub for institutions and partners.
v1.5는 Receipt·배치·듀얼 앵커(EVM+HLF)·witness·정책을 운영합니다. v2 px402·AA·PAID는 opt-in sidecar로 코드 연동 완료 — 기본 정산 경로는 그대로입니다.
v1.5 runs Receipt, batch, dual anchor (EVM+HLF), witness, and policy. v2 px402, AA, and PAID are opt-in sidecars — wired in code; the default settlement path is unchanged.
경쟁 버전이 아니라 계층 분리입니다. 아래 네 축이 오늘 코드·문서·게이트 기준입니다.
Not competing releases — layer separation. Four axes below match today’s code, docs, and gates.
정산 커널Settlement kernel
Receipt FSM · payloadHash SHA-256 · BatchPhase · 기관형 쿼럼 · 멱등 · state-proof
Receipt FSM · SHA-256 payloadHash · BatchPhase · institutional quorum · idempotency · state-proof
듀얼 앵커Dual anchor
EVM L1 + HLF PCI mirror · L1 finality · PCI audit · 메인넷 코어 17/17 static
EVM L1 + HLF PCI mirror · L1 finality · PCI audit · mainnet core 17/17 static
v2 opt-inv2 opt-in
Px402 · AA execution · PAID Intent+Policy · agent/escrow SDK — 커널 기본 경로 불변
Px402 · AA execution · PAID Intent+Policy · agent/escrow SDK — kernel default unchanged
검증·온보딩Gates & onboarding
check:v15-branch-integration · hybrid 57/57 · 0 gap blocking · 허브·Explorer·문서 SSOT
check:v15-branch-integration · hybrid 57/57 · 0 gap blocking · hub · Explorer · docs SSOT
흔한 마찰Common friction
PayChain의 답How PayChain helps
Receipt 하나로 실행과 정산을 이어 붙이고, 배치·앵커·검증으로 나중에도 같은 근거를 꺼낼 수 있습니다.
One Receipt spine links execution and settlement, with batches, anchors, and verification you can cite later.
지갑 없이도 아래 샌드박스에서 흐름을 가볍게 눌러볼 수 있어요.
No wallet needed — try the sandbox below to walk through a sample flow.
같은 인프라를, 역할에 맞게 읽도록 섹션을 나눴습니다. 은행·개발자·커머스/PG가 각자 필요한 문장만 빠르게 집을 수 있게요.
Same infrastructure, three lenses—so banks, builders, and commerce teams can scan what matters to them.
리스크·감사·규제 대화에 필요한 정산 설명·로그·앵커를 한 레이어에서 맞춥니다.
Settlement narrative, logs, and anchors for risk, audit, and regulatory conversations—without forcing everyone onto one chain mental model.
은행·금융 안내 →Banking & finance →HTTP API·상태머신·공개 capabilities로 빠르게 붙고 로컬에서 끝까지 리허설합니다.
HTTP APIs, state machines, and public capability JSON—wire fast and rehearse end-to-end locally.
수수료·지연·운영 콜을 줄이려면 한 영수증 줄기로 PG·웹3·정산을 맞추는 것이 유리합니다.
Reduce fee drag and ops tickets by aligning PG, Web3, and settlement on one receipt spine.
가치 요약 →Value summary →Vision · v2 → v1.5 → Layer BVision · v2 → v1.5 → Layer B
pay-chain-1.5 = Settlement OS(정산 커널). pay-chain-2 = 같은 커널 위에 px402·MCP·Agent/Escrow·ieum 제품 레이어. 경쟁 버전이 아니라 계층이 다릅니다 — v1.5 강점(Receipt·기관형 쿼럼·witness)을 유지하고 v2는 선별 백포트합니다. 층 B(fraud proof, permissionless withdrawal)는 로드맵. SSOT: docs/PROGRAMMABLE_PAYMENT… §13 · 5부작.
pay-chain-1.5 = Settlement OS kernel. pay-chain-2 = px402, MCP, agent/escrow, and product layers (e.g. ieum) on top. Not competing releases — different layers. We keep v1.5 strengths and selectively backport v2. Layer B stays on the roadmap. SSOT: programmatic payment doc §13 · 5-part series.
v2 북극성v2 north star
Settlement OS + px402 + PayFiSettlement OS + px402 + PayFi
v1.5 오늘v1.5 today
Receipt · S10.3 witness · CI 게이트Receipt · S10.3 witness · CI gates
층 B 로드맵Layer B roadmap
Trust P0 · #10 sequencerTrust P0 · #10 sequencer
파일럿 (Railway)Pilot (Railway)
postgres · mock anchor (live Sepolia 다음)postgres · mock anchor (live Sepolia next)
Architecture · v1.5 + v2 흡수Architecture · v1.5 + v2 absorption
PayChain은 단일 L2가 아니라 Settlement Layer입니다. OP Stack·Avalanche·XRPL·PCI는 실행·앵커 레일이고, Receipt·배치·witness가 SSOT입니다. v2의 px402·ieum·NetworkRegistry는 이 커널 위에 단계적으로 올립니다.
PayChain is a settlement layer, not “just another L2.” OP Stack, Avalanche, XRPL, and PCI are execution and anchor rails; Receipt, batch, and witness stay SSOT. v2 px402, ieum, and NetworkRegistry land incrementally on this kernel.
v1.5 오늘 (커널)v1.5 today (kernel)
InstitutionalSettlementManager 기관형 쿼럼InstitutionalSettlementManager institutional quorumv2 로드맵 (선별 흡수)v2 roadmap (selective backport)
v1.5 Settlement Kernel은 추후 모듈 단위(Receipt VM, SDK, 앵커, Explorer 등)로 분리·재활용할 수 있게 설계됩니다. 파트너는 전체 스택이 아니라 필요한 조각만 도입할 수 있습니다.
The v1.5 settlement kernel is built for future modular reuse—Receipt VM, SDK, anchors, Explorer, and more—so partners can adopt slices, not only the full stack.
PayChain Timeline · PMOPayChain Timeline · PMO
테스트넷, ieum PoC, PX402, PayWorlds, 풀 매니저, 정산 자동화까지 — 파트너 공유용 실행 일정 요약입니다. 2026-06-10 기준 핵심 리스크는 퍼블릭 테스트넷 최소 온보딩 패키지(문서·SDK·샌드박스)입니다.
Testnet, ieum PoC, PX402, PayWorlds, pool manager, and settlement automation — a partner-facing execution snapshot. As of 2026-06-10, the key risk is the minimum public-testnet onboarding package (docs, SDK, sandbox).
현재 단계Current stage
퍼블릭 테스트넷 준비Public testnet prep
다음 마일스톤Next milestone
PayChain 퍼블릭 테스트넷 오픈PayChain public testnet open
리스크 수준Risk level
보통Moderate
진행 현황Progress
5건 진행 · 2건 완료 (PayTime)5 in progress · 2 done (PayTime)
내부 테스트넷 검증 및 정산 플로우 확인. v1.5 hybrid 백포트·CI v1.5 green 기준으로 로컬·스테이징 게이트를 닫았습니다.
Internal testnet validation and settlement flow checks — local/staging gates closed on v1.5 hybrid backport and green CI v1.5.
외부 파트너·개발자 대상 퍼블릭 테스트넷 오픈. 단순 RPC 공개가 아니라 안정 RPC/WS, Explorer, faucet 또는 테스트 토큰, 개발자 문서, SDK, sandbox, receipt proof verifier, 운영 runbook까지 포함해야 합니다.
Public testnet for partners and developers. Not just an RPC URL: it should include stable RPC/WS, Explorer, faucet/test tokens, developer docs, SDK, sandbox, receipt proof verifier, and operations runbook.
PayChain L2(chainId 42472) 위 KSC·StableVault·PaymentManager 배포, 이중승인 발행, 가맹점 정산, Receipt 등록, Batch/Anchor, Merkle Proof까지 E2E 검증. 기존 Avalanche/XRPL 경로는 무회귀 유지.
On PayChain L2 (chainId 42472): KSC, StableVault, PaymentManager, dual-approval issuance, merchant settlement, Receipt registration, Batch/Anchor, and Merkle Proof validated E2E. Existing Avalanche/XRPL paths stayed regression-free.
로컬 Ledger 검증을 운영형 PayChain Ledger 연동으로 전환하고, Receipt 영속·멀티테넌트 구조를 검증합니다.
Move from local Ledger validation to operational PayChain Ledger integration, validating persisted Receipts and multi-tenant structure.
체인 DB 스키마 v17 프로비저닝 완료. Shared Pooler Session URI → Railway DATABASE_URL 적용 후 ledgerStore=postgres 전환. IPv4 proxied · ?sslmode=require.
Chain DB schema v17 provisioned. Shared Pooler Session URI → Railway DATABASE_URL → ledgerStore=postgres. IPv4 proxied · ?sslmode=require.
P0 리스크: 퍼블릭 테스트넷 최소 온보딩 패키지 — V1.5/V2 역할 구분, ieum PoC 예제, MCP/SDK/Receipt Proof/Explorer 사용법, sandbox write/read-only MCP 가이드.
P0 risk: minimum onboarding for public testnet — V1.5/V2 role split, ieum PoC example, MCP/SDK/Receipt Proof/Explorer usage, sandbox write/read-only MCP guide.
퍼블릭 테스트넷 성능·장애 대응 체계화. 관측·SLO·릴리스 게이트와 연동합니다.
Performance and incident response for public testnet — tied to observability, SLO hints, and release gates.
검토 중이 아니라 client track 구현 진행: escrow-sdk, agent-sdk, MCP read/agent, CLI/kit, Settlement OS px402 listener. 기본 경로는 정산 커널 유지, production write는 제품 ADR 후.
Not just “under review”: client track in progress — escrow-sdk, agent-sdk, MCP read/agent, CLI/kit, Settlement OS px402 listener. Default path keeps the settlement kernel; production writes wait for product ADR.
PX402_ESCROW_ADDRESS 등 외부 주소 수령 후 env 설정·live E2E 검증. Production cutover는 Q3 검토.
After receiving PX402_ESCROW_ADDRESS and related external addresses: set env and run live E2E. Production cutover remains Q3 review.
Q3 프로덕션 전환 검토 및 scope gate. Escrow live E2E 결과·파트너/법무 승인 후 진행합니다.
Q3 production cutover review and scope gate, after escrow live E2E plus partner/legal approval.
초기 앱 생태계 및 가맹점·사용자 접점. PayHub·랜딩 허브와 연결되는 파트너 온보딩을 전제합니다.
Early app ecosystem and merchant/user touchpoints — partner onboarding wired to PayHub and this landing hub.
실제 가맹점 정산 파일럿(라스트마일 검증). Receipt SSOT·배치·앵커 증빙으로 운영 대화를 닫습니다.
Live merchant settlement pilot — close the ops narrative with Receipt SSOT, batches, and anchor evidence.
유동성 라우팅 정책·운영자 워크플로 설계. PCI 풀 매니저 운영의 선행 단계입니다.
Liquidity routing policy and operator workflows — precursor to PCI pool manager operations.
유동성 관리·라우팅 레이어 운영. PCI 앵커·대사·관측 경로와 연동합니다.
Liquidity management and routing layer ops — integrated with PCI anchor, reconciliation, and observability paths.
결제·정산·유동성 운영 자동화 에이전트. 파트너 공개 전 범위·보안 정책 확정이 선행됩니다.
Automation for payment, settlement, and liquidity ops — scope and security policy before partner visibility.
메인넷 준비 전 PCI 토큰 유틸리티 범위·규제 해석 검토(내부).
Internal PCI token utility scope and regulatory review before mainnet readiness.
메인넷 런칭 기준 최종 게이트 리뷰. 운영 MVP·보안·검증 마감과 함께 진행합니다.
Final gate review for mainnet launch — alongside operational MVP, security, and verification closure.
PayTime에서 전체 타임라인 보기Full timeline on PayTime 기술 로드맵 (STATUS_AND_ROADMAP)Technical roadmap (STATUS_AND_ROADMAP)
글로벌 제품 랜딩에서 흔한 Explain → Try → Build 순서를 PayChain에 맞춰 네 단계로 고정했습니다.
We follow the familiar explain → try → build ladder, tuned for PayChain.
왜 레이어가 필요한지, 실행·Receipt·정산 흐름을 먼저 훑습니다.
Scan why the layer exists and execution, receipt, settlement.
샌드박스 시뮬레이션에서 시나리오 프리셋을 눌러 경로·상태를 확인합니다.
Use sandbox presets to see a sample route and status.
로컬 Ledger를 띄운 뒤 라이브 API·운영 허브로 health·역량·공개 엔드포인트를 확인합니다.
Run Ledger locally, then use live API and the operations hub for health and capabilities.
Continue to , institutional & security, and observability & audit.
PayChain은 지금도 붙여 보고 운영을 리허설할 수 있는 경로를 갖추고 있습니다. 동시에 글로벌 기준의 신뢰·보안·확장성은 계속 다듬어 가는 여정입니다 — 파트너와 함께 성숙시키는 제품입니다.
PayChain is ready for wiring and operational rehearsal today, while global-grade trust, security, and scale keep maturing—a product we grow with partners.
지금 경험할 수 있는 것Experience today
차별점Why PayChain
로드맵Road ahead
이 페이지는 비전과 체험에 집중합니다. 스키마·릴리스 게이트·API 상세는 개발자 문서 탭과 GitHub 문서에서 이어집니다.
This page focuses on vision and hands-on feel. Schemas, release gates, and API depth continue in Developer docs and on GitHub.
영수증·상태 전이·배치·앵커를 한 식별자 체계로 묶어, 나중에 감사·대사·온체인 증빙까지 같은 줄기로 설명합니다.
Receipts, transitions, batches, and anchors share one identity spine—so audit, reconciliation, and on-chain evidence tell the same story.
앵커 제출·브리지 정합·출력 검증·공개 메타데이터까지 — L2 클라이언트를 포크하기 전에 어댑터 경계에서 붙일 수 있게 설계했습니다.
Anchor submission, bridge alignment, output checks, and public metadata—integrate at the adapter boundary before forking L2 clients.
데이터 가용성·검증·챌린지·배치 증빙·선택형 상태 증명과 메트릭으로 “무엇이 언제 확정됐는지”를 기계가 읽을 수 있게 노출합니다.
DA, verification, challenges, batch evidence, optional state proofs, and metrics expose machine-readable finality signals.
다중 노드 운영, 공개 네트워크 활성화 상태, 자동화된 E2E 점검으로 스테이징을 반복 검증할 수 있습니다.
Multi-node ops, public activation signals, and automated E2E checks help teams rehearse staging with confidence.
PayChain은 실행(Execution)과 정산(Settlement)을 같은 제품 안에서 분리해 둡니다. 둘 다 필요하지만, 최적화 목표가 다릅니다.
PayChain keeps Execution and Settlement distinct inside one product. Both matter, but they optimize for different goals.
결제 실행Payment execution
정산Settlement
한 줄: 실행은 빠르게 움직이게, 정산은 천천히 틀리지 않게 — 둘을 한 흐름으로 묶되 책임은 나눕니다.In one line: execution optimizes for moving fast; settlement for being right later—one flow, split responsibilities.
디앱·파트너 선제 빌드: 일반 EVM과도 맞추되 PayChain에서 더 잘 먹히는 연동 포인트·모듈 아이디어는 DEVELOPER_GUIDE — Builder edge (EVM + PayChain) 에 정리했습니다.Build ahead (dApps & partners): stay EVM-compatible while leaning into PayChain-native hooks—see DEVELOPER_GUIDE — Builder edge (EVM + PayChain).
AI 에이전트·자동화 워크플로는 사람과 동일한 HTTP API로 Receipt를 만들고 상태를 전이합니다. 핵심은 “한 번 더 불렀을 때 안전한가?”입니다.
Agents and workflows use the same HTTP APIs as humans to create receipts and drive transitions. The key question is idempotency: what happens if the tool calls twice?
결제는 빠르게 처리돼야 하고, 정산은 나중에도 분명히 설명돼야 합니다. PayChain은 이 둘을 하나의 흐름으로 연결해 운영 부담과 파트너별 예외 처리를 줄입니다.
Payments must move fast, while settlement must still be provable later. PayChain connects both in one operating flow and reduces partner-by-partner complexity.
카드, 계좌, 스테이블코인이 달라도 같은 흐름으로 붙일 수 있어 파트너별 예외 로직이 줄어듭니다.
Cards, bank rails, and stablecoins can plug into one consistent flow, reducing partner-specific exceptions.
나중에 “언제 무엇이 확정됐는가”를 다시 설명할 때, 같은 기준과 같은 증거를 볼 수 있습니다.
When teams need to explain what finalized and when, they can look at the same evidence and timeline.
사람이 보든 자동화 도구가 보든 같은 흐름과 같은 인터페이스를 기준으로 움직일 수 있습니다.
Humans and automation can work from the same flow and the same interfaces.
결제 팀, 정산 팀, 감사 대응이 서로 다른 언어로 일하는 대신 같은 흐름을 공유할 수 있습니다.
Payment teams, settlement teams, and audit teams can work from one shared operating model instead of three different ones.
기존 시스템은 그대로 두고, 운영자가 보는 흐름만 하나로 맞춥니다. 결제 처리와 정산 확인을 같은 기준으로 이어서 볼 수 있게 합니다.
Keep existing systems in place and unify only the operating view. That lets payment handling and settlement confirmation be read as one connected flow.
복잡한 체인 구조를 다 알지 않아도 됩니다. 중요한 것은 결제가 어떻게 처리됐고, 정산이 언제 끝났는지를 같은 기준으로 볼 수 있다는 점입니다.
Teams do not need deep chain knowledge. What matters is seeing how a payment was handled and when settlement completed through one consistent lens.
기존 PG·코어·정산 프로세스를 버리는 것이 아니라, 그 위에 운영 기준과 확인 근거를 덧대는 방식입니다. 소비자 앱이 아니라 은행·PG·감사·웹3 파트너를 위한 운영 인프라입니다.
This does not replace existing PG, core, or settlement processes. It adds a clearer operating layer and confirmation trail on top of them. It is operational infrastructure for banks, PGs, auditors, and Web3 partners.
여러 레일을 붙여도 운영자는 하나의 흐름으로 보고, 나중에 정산 확인과 감사 대응까지 이어갈 수 있습니다.
Even across many rails, operators get one flow they can manage and later use for settlement confirmation and audit response.
PayChain은 소비자 앱이 아니라, 파트너 시스템 뒤에서 결제 흐름과 정산 확인을 정리해 주는 운영 레이어입니다.
PayChain is not a consumer app. It sits behind partner systems and organizes payment flow with settlement confirmation.
먼저 결제 요청과 처리 상태를 한 흐름으로 정리하고, 이후 정산이 끝났는지와 무엇이 확정됐는지를 같은 기준으로 남깁니다. 그래서 운영팀과 파트너가 나중에도 같은 설명을 공유할 수 있습니다.
개별 거래를 모두 올리는 대신, 배치 단위의 확인 정보만 남겨 비용과 운영 부담을 줄이는 것이 기본 원칙입니다.
First, payment requests and processing states are organized into one flow. Then the platform leaves a clear record of what settled and what became final, so operators and partners can refer to the same explanation later.
Instead of pushing every trade individually, the design keeps only batch-level confirmation data to control cost and complexity.
실행 ≠ 정산이지만, 운영자와 시스템은 같은 Receipt를 기준으로 움직입니다.
Execution is not settlement, yet operators and systems move against the same receipt.
한 줄 요약: Receipt(무엇) → Batch(언제·얼마) → Anchor(변조 없음) → Witness(외부 검증). 기술 용어가 익숙하지 않아도 이 네 단어만 기억하면 충분합니다.
In one line: Receipt (what) → Batch (when/how much) → Anchor (untampered) → Witness (external check). Four words are enough — no deep technical background needed.
로컬에서 Ledger를 띄운 뒤 아래에서 상태와 역량을 바로 확인해 보세요. 상세 명령·엔드포인트 목록은 개발자 문서 탭과 빠른 시작 가이드에 있습니다.
Run Ledger locally, then probe health and capabilities below. Commands and endpoint detail live in Developer docs and the quick start guide.
실제 자금이 아닌 설명용 시나리오입니다. 금액과 레일을 고른 뒤 시뮬레이션하면 Receipt 경로와 예상 상태가 표시됩니다.
Illustration only—no funds move. Pick an amount and rail, run the simulation, and see a sample receipt path and status.
경로Route:
Receipt (샘플)Receipt (sample):
시뮬레이션 결과는 교육용이며, 실제 Ledger 응답과 다를 수 있습니다. 실연동은 라이브 연결을 사용하세요.
Sandbox output is educational and may differ from a real Ledger. Use live connection for real responses.
3단계로 시작하기Start in three steps
라이브 연결Live connection
Ledger가 실행 중이면, 이 브라우저에서 접근 가능한 API Base URL을 입력한 뒤 버튼을 눌러 응답을 확인하세요. 접근 제어가 켜진 환경에서는 선택적으로 API 키를 넣을 수 있습니다.
With Ledger running, enter an API base URL this browser can reach, then tap the buttons. If access control is enabled, optionally add your API key.
공개 조회 — 네트워크 상태, 역량 색인, OP 연동 메타, 신뢰 로드맵, 배처·순서화, 배치 증빙을 한 번에 살펴볼 수 있습니다.
Public reads — network status, capability index, OP integration metadata, trust roadmap, batcher/sequencing, and batch witness.
랜딩이 Ledger와 다른 도메인에 있으면 브라우저 보안 정책으로 요청이 막힐 수 있습니다. 같은 기기에서 열거나 API 쪽 CORS 설정을 맞추면 됩니다. 자세한 방법은 개발자 문서를 참고하세요.
If this site and Ledger are on different origins, the browser may block requests. Open from the same machine or align CORS on the API—see developer docs for detail.
시작 순서 (3단계)Three steps to start
Receipt 시뮬레이션·기능별 CLI·인프라 명령은 탭에서 이어집니다.
Receipt simulation, full CLI walkthrough, and infra commands continue in the tab.
Medium Series
Medium Series
v2 Settlement OS를 중심에 두고, v1.5 정산 커널·witness·게이트가 오늘 무엇을 제공하는지 Lim PP 관점으로 설명합니다. Medium 원고: docs/articles/export/ko/ · export/en/ · npm run export:medium-articles.
v2 Settlement OS at the center — what v1.5 kernel, witness, and gates ship today. Medium drafts: docs/articles/export/ko/ · export/en/ · npm run export:medium-articles.
결제는 해결됐지만 신뢰는 아니다 — 비어 있는 settlement layer.
Payments solved, trust not — the empty settlement layer.
읽기Readtransaction hash ≠ 금융 기록. Receipt와 정산 상태머신.
A hash is not a financial record — Receipt and the state machine.
읽기ReadPCI는 신뢰를, PayChain은 실행을. HLF + EVM 계층화.
PCI provides trust, PayChain execution — HLF + EVM layered.
읽기ReadEVM은 정체성이 아니라 배포 경로. TVL보다 Execution Volume.
EVM is distribution, not identity — Execution Volume over TVL.
읽기ReadPayFi · PX402(Financial API Layer) · agentic finance — parked 로드맵.
PayFi, PX402 as a Financial API Layer, agentic finance — parked roadmap.
읽기Read각 편은 Mechanics · Limits · Risks + 파일럿 스냅샷. 발행 전 docs/articles/MEDIUM_PUBLISH_AUDIT.md와 export KO/EN 품질 검토.
Each part: Mechanics · Limits · Risks + pilot snapshot. Before publish: MEDIUM_PUBLISH_AUDIT.md and export KO/EN review.
Research · Korean draft v0.1
Research · Korean draft v0.1
논문 v0.1은 PayChain을 “또 하나의 실행 체인”이 아니라, 다중 네트워크 결제와 Agentic Commerce의 실행 결과를 Receipt·Batch·Anchor·Proof·Reconciliation으로 정규화하는 정산 런타임으로 정의합니다.
Paper v0.1 defines PayChain not as another execution chain, but as a settlement runtime that normalizes multi-network payments and agentic commerce outcomes into Receipt, Batch, Anchor, Proof, and Reconciliation.
PayChain: A Receipt-Centric Verifiable Settlement Runtime for Multi-Network Payments and Agentic Commerce
현대 결제 시스템에 부족한 것은 또 하나의 실행 체인이 아니라, 결제 이후의 정산·증빙·감사·대사를 검증 가능하게 만드는 Settlement Runtime입니다.
Modern payment systems do not lack another execution rail; they lack a Settlement Runtime that makes post-payment settlement, proof, audit, and reconciliation verifiable.
Transaction hash alone is insufficient as a financial settlement object. tx hash는 거래 존재를 보여주지만, 왜 발생했고 누가 승인했으며 어떻게 정산되었는지는 설명하지 못합니다.
Transaction hash alone is insufficient as a financial settlement object. It shows existence, not why it happened, who approved it, and how it settled.
PayChain은 x402·ERC-8183·계정 추상화와 경쟁하지 않습니다. 이들은 실행 계층이고, PayChain은 실행 이후의 정산·증빙·감사·대사를 담당하는 Receipt 중심 Settlement Runtime입니다.
PayChain does not compete with x402, ERC-8183, or account abstraction. They are execution layers; PayChain is the Receipt-centric settlement runtime for proof, audit, reconciliation, and disputes after execution.
한국어 통합 원고 v0.1 기준입니다. 공개 문서에는 논문 핵심 주장과 구현 정합만 반영하고, 내부 자료·키·운영 세부값은 제외합니다. 개발자용 매핑은 docs/PAYCHAIN_PAPER_ALIGNMENT.md를 기준으로 합니다.
Based on the Korean integrated draft v0.1. Public docs carry the thesis and implementation alignment only; internal reports, keys, and private operational values are excluded. Developer mapping lives in docs/PAYCHAIN_PAPER_ALIGNMENT.md.
세일즈 덱 · 기관용
Sales deck · for institutions
PayChain V2 = Payment + Settlement + Proof + Financial Execution Infrastructure. V2는 PX402·MCP·Agent SDK·ieum 통합·다중 네트워크 추상화를 메인 서사로 보여주고, V1.5의 Receipt SSOT·Batch·Anchor·Reconciliation·Institutional Governance는 그 밑바닥의 안정성 근거로 둡니다.
PayChain V2 = Payment + Settlement + Proof + Financial Execution Infrastructure. V2 is the main narrative — PX402, MCP, Agent SDK, ieum integration, and multi-network abstraction — while V1.5's Receipt SSOT, Batch, Anchor, Reconciliation, and Institutional Governance remain the trust kernel underneath.
여러 결제수단(스테이블코인·은행·카드·PG)의 거래를 하나의 정산·증빙 기록으로 묶어, 마감·대사·감사가 스스로 설명되게 만드는 정산 인프라입니다.
It ties transactions across rails (stablecoin, bank, card, PG) into one settlement and proof record, so close, reconciliation, and audit explain themselves.
청중을 고르면 핵심 슬라이드만 추려 보여줍니다. 인쇄 시 “전체”로 두면 전체 덱이 저장됩니다.
Pick an audience to focus the deck. Keep “All” when printing to save the full deck.
이 덱은 파트너·기관 검토용 자료입니다. 구현 상태는 공개 network-activation-status로 상시 확인 가능하며, 미완 항목은 로드맵으로 명시합니다.
This deck is for partner and institutional review. Implementation status is always verifiable via the public network-activation-status; roadmap items are labeled as such.
조달 검토용 · 1-pager
For procurement · one-pager
조달·정보보안·감사 부서가 먼저 묻는 항목을 한 장으로 정리했습니다. 현재 구현과 로드맵을 구분해 정직하게 표기합니다.
The questions procurement, infosec, and audit ask first — on one page. We label what is implemented today vs roadmap, honestly.
고객·계약·수수료 등 민감 데이터는 공개 체인에 올리지 않습니다. 온체인에는 해시 기반 증거(Anchor)만 남겨 내용은 비공개, 무결성은 검증 가능하게 유지합니다.
Sensitive data (customer, contract, fees) is never put on a public chain. Only hash-based evidence (Anchor) goes onchain — content stays private while integrity stays verifiable.
공개 조회는 무인증, 쓰기는 운영자·배처·감사자 역할 키로 분리. 승인·재처리·동결은 2인 승인(4-eyes) 정책 훅으로 통제합니다.
Public reads are open; writes are split by operator, batcher, and auditor role keys. Approve, reprocess, and freeze run through two-person (4-eyes) policy hooks.
서명 키를 운영 서버에서 분리(별도 서명 서비스), HMAC 인증·IP 허용목록·KMS 연동(선택), 키 로테이션·인시던트 런북 제공.
Signing keys are isolated from app servers (separate signer service), with HMAC auth, IP allowlist, and KMS (optional), plus key-rotation and incident runbooks.
모든 정산은 변조 불가 증거(Anchor)와 외부 검증(Witness)에 연결되고, 기간별 증빙을 내보내기(Export)할 수 있습니다.
Every settlement links to tamper-evident proof (Anchor) and external verification (Witness), with period-based evidence export.
멱등 처리(중복 방지), 배처 장애 후 이어서 처리(crash-resume), 영속 스토어(Postgres) 기반으로 재배포 후에도 이력이 유지됩니다.
Idempotency (no duplicates), batcher crash-resume, and a persisted store (Postgres) keep history across redeploys.
현재 파일럿 단계로 SOC 2·ISO 27001·PCI-DSS 등 공식 인증은 미보유(로드맵)입니다. 라이브 앵커·운영 권한·실 PCI 연동도 로드맵으로 명시하며 과장하지 않습니다.
At pilot stage, formal certifications (SOC 2, ISO 27001, PCI-DSS) are not yet held (roadmap). Live anchoring, production access control, and real PCI integration are also labeled as roadmap — no overclaim.
| 영역Area | PayChain | 고객 / 운영자Customer / operator |
|---|---|---|
| 정산·증빙 엔진Settlement & proof engine | 제공·유지provide & maintain | 연동·검수integrate & verify |
| 키·자격증명Keys & credentials | 서명 서비스·런북signer service & runbook | 보관·로테이션 승인custody & rotation approval |
| 정책 (한도·승인)Policy (limits, approvals) | 정책 엔진·훅policy engine & hooks | 규칙 정의·승인자 지정define rules & approvers |
| 인프라·가용성Infra & availability | 배포 가이드·런북deploy guide & runbook | 호스팅·모니터링hosting & monitoring |
구현 상태는 공개 network-activation-status에서 상시 확인할 수 있습니다.
Implementation status is always verifiable at the public network-activation-status.
다음 단계 · 템플릿
Next step · template
파일럿을 “담당자·일정·완료 기준”으로 합의하기 위한 양식입니다. 인쇄해서 그대로 채워 쓰셔도 됩니다.
A form to agree the pilot with owners, dates, and exit criteria. Print and fill it in as-is.
| 단계Step | 활동Activity | 담당Owner | 목표일Target date | 완료 기준Exit criteria |
|---|---|---|---|---|
| D+0 | 소개 콜 · 보안 1-pager·ROI 모델 공유Intro call · share security one-pager & ROI model | PayChain + 고객Customer | 범위·이해관계자 확정scope & stakeholders agreed | |
| D+30 | 샌드박스 · Receipt→Batch→Anchor 흐름 검토Sandbox · review Receipt→Batch→Anchor flow | PayChain | 기술 검토 통과tech review passed | |
| D+60 | 파일럿 · 1개 레일/정산 흐름 + KPIPilot · one rail/flow + KPIs | PayChain + 고객Customer | KPI·증빙 합의KPIs & proof agreed | |
| D+90 | 라이브 확장 · 권한 키·라이브 앵커·대사/감사Live expansion · keys, live anchor, recon/audit | 고객Customer | 운영 전환 승인go-live approval |
Developer
Developer
스키마·환경 변수·릴리스 게이트는 GitHub 문서와 스크립트가 기준입니다. 제품 탭은 비전·체험, 여기는 연동·검증·운영에 집중합니다.
Schemas, env, and release gates live in GitHub docs and scripts. The Product tab is vision-first; here we focus on integration, verification, and ops.
Ledger API, 배치·앵커, 검증, CLI·E2E는 아래 링크와 저장소를 따라가면 됩니다.
Ledger API, batching, anchoring, verification, CLI, and E2E — follow the links below and the repo.
25차 (2026-06-28): 메인넷 코어 17/17 · hybrid 57/57 · v2 remote parity · PAID→Policy hook · H17 operator · 듀얼 앵커 mirror. SSOT: V15_V2_TECHNICAL_STATUS · PROJECT_MASTER_TODO. 검증: npm run check:v15-branch-integration · npm run operator:h17-live-complete.
Batch 25 (2026-06-28): Mainnet core 17/17 · hybrid 57/57 · v2 remote parity · PAID→Policy hook · H17 operator · dual anchor mirror. SSOT: V15_V2_TECHNICAL_STATUS · PROJECT_MASTER_TODO. Gates: npm run check:v15-branch-integration · npm run operator:h17-live-complete.
공개 URL: Ledger https://paychain-production.up.railway.app/api · Landing landing-six-pied-84.vercel.app · Explorer explorer-seven-wine.vercel.app · 허브 /app/.
Public URLs: Ledger https://paychain-production.up.railway.app/api · Landing landing-six-pied-84.vercel.app · Explorer explorer-seven-wine.vercel.app · Hub /app/.
v1.5 + v2 Hybrid (2026-06): signer·Merkle·RBAC E2E, L1 finality, Idempotency-Key, 배처 crash-resume, AppConfig(da/export 포함). 로컬: npm run rehearsal:hybrid-staging:quick · Anvil: npm run step2:anvil:hybrid-rbac. CI: v1.5 push → CI v1.5 워크플로 (hybrid gate + Anvil E2E). 상세: DEVELOPER_GUIDE · STATUS_AND_ROADMAP.
v1.5 + v2 Hybrid (Jun 2026): signer, Merkle, RBAC E2E, L1 finality, Idempotency-Key, batcher resume, AppConfig (incl. da/export). Local: npm run rehearsal:hybrid-staging:quick · Anvil: npm run step2:anvil:hybrid-rbac. CI: v1.5 push → CI v1.5 workflow (hybrid gate + Anvil E2E). Details: DEVELOPER_GUIDE · STATUS_AND_ROADMAP.
최근 반영 요약: OP Stack 맞춤 메타데이터(spec 0.2), 배처·순서화 역량(0.2), 네트워크 활성화·신뢰 로드맵 공개 필드, 상태 증명 인출·포털 관련 E2E·점검 스크립트. 전체 변경·우선순위는 TODOS_AND_NETWORK, WITHDRAWAL_AND_VERIFICATION, OP_STACK_GUIDE를 참고하세요.
Recent highlights: OP Stack custom metadata (spec 0.2), batcher/sequencer capabilities (0.2), public network activation and trust roadmap fields, state-proof withdrawal and portal-related E2E and checks. Priorities: TODOS_AND_NETWORK, WITHDRAWAL_AND_VERIFICATION, OP_STACK_GUIDE.
허브·SDK·테스트: 라이브 허브(/app/)와 SDK로 공개 역량·앵커·OP 메타를 병렬 조회할 수 있고, 통합·전체 테스트 스위트에 공개 JSON 회귀가 포함됩니다. 명령어·경로 목록은 DEVELOPER_GUIDE·TESTING_AND_QUALITY를 보세요.
Hub, SDK, tests: The live hub (/app/) and SDK fetch public capabilities, anchors, and OP metadata in parallel; integration and full test suites include public JSON regression. Commands and paths: DEVELOPER_GUIDE and TESTING_AND_QUALITY.
GitBook-ready Dev Docs: 개발자 가이드는 단일 GitBook 페이지로 올릴 수 있도록 개요·v1.5/v2 경계·SDK/CLI·파트너 온보딩·검증 게이트를 상단에 정리했습니다. px402 P2 skeleton은 npm run check:px402-integration으로 로컬 Anvil smoke까지 확인합니다.
GitBook-ready Dev Docs: The developer guide now starts with a single-page GitBook overview: v1.5/v2 boundaries, SDK/CLI onboarding, partner checklist, and validation gates. The px402 P2 skeleton is covered by npm run check:px402-integration, including local Anvil smokes.
파일럿·운영 MVP(합의 이전): 스테이징에서 닫을 체크리스트 A–G·배처 기초 정책(§9.5 D)은 INSTITUTIONAL_AND_BD §9.5 · TODOS_AND_NETWORK §7.2. 저장소 루트에서 오프라인 자동 묶음 npm run check:operational-mvp-preflight (공개 JSON 스키마·층 A 규칙·배치 witness·선택 B1).
Pilot / operational MVP (pre–protocol consensus): Checklist A–G and batcher baseline policy (§9.5 D) live in INSTITUTIONAL_AND_BD §9.5 and TODOS_AND_NETWORK §7.2. From repo root, run npm run check:operational-mvp-preflight for an offline bundle (public JSON schema, layer-A rules, batch witness, optional B1).
PCI·프로덕션 네트워크(2026-04): 메인넷(HLF)은 보수적 앵커 레이어(put/get/exists)·멱등 batchId. PCI_FABRIC_REST_BASE_URL + Postgres anchor_records(v14) + Ledger 앵커 검증 워커로 원격 해시 대사. OP 실행 코어 포크가 아니라 ② 연동면 중심 — L2_AND_ROLLUP §4a · GLOSSARY ①②③.
PCI & production network (Apr 2026): PCI mainnet (HLF) is a conservative anchor layer (put/get/exists, idempotent batchId). With PCI_FABRIC_REST_BASE_URL, Postgres anchor_records (migration v14), and the Ledger anchor verify worker, we reconcile remote hashes—not an OP execution-core fork, mostly layer-② integration — L2_AND_ROLLUP §4a, GLOSSARY ①②③.
공개 audit·관측·Scanner·Explorer (후속): 무인증 GET /api/public/anchor-audit/:batchId · 운영자 GET /api/anchors의 pciAudit · 요약 pciAnchorAudit 및 알림 PCI_ANCHOR_MISMATCH / PCI_VERIFY_PENDING_DELAY · Prometheus paychain_pci_anchor_*(요약 갱신 시 동기) — OBSERVABILITY · QUICK_REFERENCE. Scanner는 SCANNER_PCI_VERIFY_INTERVAL_MS + API 키로 POST /api/anchors/verify/run 주기 호출·GET /health의 pciVerifyPoller. Explorer 앵커 표에 PCI 대사 열·상세에 공개 audit 병합. 남은 투두 요약: TODOS_AND_NETWORK 「남은 투두 스냅샷」.
Public audit, observability, Scanner, Explorer (follow-on): Unauthenticated GET /api/public/anchor-audit/:batchId; operator GET /api/anchors includes pciAudit; summary exposes pciAnchorAudit plus PCI_ANCHOR_MISMATCH / PCI_VERIFY_PENDING_DELAY; Prometheus paychain_pci_anchor_* (updated when observability summary runs) — OBSERVABILITY, QUICK_REFERENCE. Scanner can periodically call POST /api/anchors/verify/run with SCANNER_PCI_VERIFY_*; GET /health exposes pciVerifyPoller. Explorer shows PCI columns and merges public audit in anchor detail. Remaining work snapshot: TODOS_AND_NETWORK (remaining todos).
라이브 허브 (Ledger·Scanner)Live hub (Ledger & Scanner) 하이브리드 SSOTHybrid SSOT ExplorerExplorer Hybrid 가이드 (API·E2E)Hybrid guide (API & E2E) 문서 색인 (docs 20개)Docs index (20 files)
관련 문서:Related docs: WITHDRAWAL_AND_VERIFICATION, INSTITUTIONAL_AND_BD (§9 운영 MVP)(§9 operational MVP), STATUS_AND_ROADMAP, TODOS_AND_NETWORK, TESTING_AND_QUALITY, Builder edge — 상태 증명 통합 플래그·Anvil E2E·공개 discovery 오프라인 검증은 ENV_SCHEMA·TESTING_AND_QUALITY에 정리되어 있습니다.— State-proof integration flags, Anvil E2E, and offline public discovery checks are documented in ENV_SCHEMA and TESTING_AND_QUALITY.
레일별 원장은 유지하고 Receipt·상태머신·Proof로 흡수합니다. 아래는 구현·운영 단에서의 구체 항목입니다.
Normalize on Receipt, state machine, and Proof while keeping each rail’s ledger. Operational detail below.
운영 핵심을 네 블록으로 요약합니다.
Four blocks for institution-grade operations.
단순 데모를 넘어서, 실제 운영으로 가기 위한 점검 경로와 확장 경로를 갖추고 있습니다. 다만 이 구역은 “이미 가능한 것”과 “실서비스 전 마무리할 것”을 함께 봐야 정확합니다.
Beyond a single demo, the product includes paths for operational checks and scale-up. Read this section as both what is already available and what still needs to close before full production.
문서:Docs: TODOS_AND_NETWORK, INSTITUTIONAL_AND_BD (§9.5 체크리스트)(§9.5 checklist), DATA_AND_PROTOCOLS, OP_STACK_GUIDE, OPERATIONS, SECURITY_POLICY_AND_SLA, STATUS_AND_ROADMAP, WITHDRAWAL_AND_VERIFICATION
제품 탭 요약에 대응하는 전체 항목입니다.
The full list behind the Product tab summary.
npm run check:operational-mvp-preflightNetwork-grade — seed drift, batch compare, W3 export/validate, OP bridge · operational MVP offline npm run check:operational-mvp-preflight에코 HTTP 스텁은 통합 연습용이며 상용 결제망을 대체하지 않습니다.
Ecosystem HTTP stubs are for integration practice, not a production payment network replacement.
한 건의 정산(Receipt)이 INIT → AUTHORIZED → COMMITTED → BATCHED → ANCHORED로 흐르는 과정을 단계별로 눌러 보세요. 이후 최종 정산·인출·탐색기 흐름은 API 레퍼런스와 로컬 예제에서 이어집니다.
Step through one Receipt: INIT → AUTHORIZED → COMMITTED → BATCHED → ANCHORED. Final settlement, withdrawals, and Explorer flows continue in the API reference and local examples below.
설명용 인터랙션Illustrative only
버튼으로 단계를 바꿔도 실제 Ledger의 Receipt와는 연결되지 않습니다. 흐름(INIT→…→ANCHORED)과 앵커 시 해시가 어떻게 보이는지 익히는 용도입니다.
Steps are not connected to a live Ledger. Use this to learn the INIT→…→ANCHORED flow and how a proof hash appears at anchor.
현재 Receipt 상태 (설명용)Receipt state (illustrative)
이 배치의 증빙 해시 (payloadHash)Proof hash for this batch (payloadHash)
—
ANCHORED 단계에서 L1에 기록되며, 감사·대사 시 이 해시로 무결성을 검증할 수 있습니다.
At ANCHORED, this hash is recorded for L1 evidence and can be used in audit and reconciliation.
멱등성: 같은 requestId로 두 번 요청하면Idempotency: same requestId twice
동일한 Receipt가 반환됩니다. 재시도·중복 전송 시에도 안전합니다.
The same Receipt is returned — safe on retries and duplicate delivery.
로컬에서 Ledger API 체험하기Try Ledger API locally
저장소를 클론한 뒤 한 번에 빌드·테스트: npm run test:full (또는 npm run setup-and-test)로 워크스페이스·Ledger API·Scanner·Relayer 빌드, 단위·E2E·통합·Scanner 헬스·Settlement/Retry Worker mock까지 실행됩니다. Ledger API만 띄우려면:
After cloning, run a full build & test with npm run test:full (or npm run setup-and-test) to build the workspace, Ledger API, Scanner, and Relayer and run unit/E2E/integration checks. To start only Ledger API:
# 1) 빌드 후 기동
npm run build:ledger
npm run start:local
# 2) 체인 상태 조회
curl -s http://localhost:3001/api/chain/status
# 3) Receipt 생성 (requestId는 멱등 키)
curl -s -X POST http://localhost:3001/api/receipts \
-H "Content-Type: application/json" \
-d '{"requestId":"demo-req-001","payload":{"amount":10000,"asset":"KRW"}}'
# 1) Build and start
npm run build:ledger
npm run start:local
# 2) Chain status
curl -s http://localhost:3001/api/chain/status
# 3) Create receipt (requestId is the idempotency key)
curl -s -X POST http://localhost:3001/api/receipts \
-H "Content-Type: application/json" \
-d '{"requestId":"demo-req-001","payload":{"amount":10000,"asset":"KRW"}}'
아래에서 업데이트된 기능별 CLI 체험을 순서대로 복사·붙여넣기하여 실행할 수 있습니다. (Linux/macOS/WSL에서 curl 사용. Windows PowerShell은 curl.exe 또는 WSL 권장.)
Below, copy and run the feature CLI walkthrough in order (use curl on Linux/macOS/WSL; on Windows PowerShell prefer curl.exe or WSL).
로컬 기본(RBAC_ENABLED 미설정·false)에서는 위 예시처럼 키 없이 호출할 수 있습니다. 프로덕션 등에서 RBAC_ENABLED=true인 경우에는 .env.example의 API_KEY_*에 맞는 X-API-Key 헤더가 필요합니다(/api/chain/health는 공개).
With the local default (RBAC_ENABLED unset or false), calls work without a key. When RBAC_ENABLED=true (e.g. production), add X-API-Key per API_KEY_* roles in .env.example (/api/chain/health stays public).
BASE=http://localhost:3001/api 기준입니다. 응답에서 id, receiptId 등을 다음 명령에 넣어 실행하세요. jq가 없으면 | jq .를 생략해도 됩니다.
Paths assume BASE=http://localhost:3001/api. Paste id, receiptId, etc. from responses into the next commands. Omit | jq . if jq is not installed.
1) 체인·조회·공개 역량 (status, blocks, payment-settlement·da·verification capabilities, …)1) Chain reads & public capabilities (status, blocks, payment-settlement, da, verification, …)
curl -s http://localhost:3001/api/chain/payment-settlement-capabilities | jq .
curl -s http://localhost:3001/api/da/capabilities | jq .
curl -s http://localhost:3001/api/verification/capabilities | jq .
curl -s http://localhost:3001/api/chain/status | jq .
curl -s http://localhost:3001/api/chain/blocks | jq .
curl -s 'http://localhost:3001/api/chain/blocks?witness=1' | jq .
curl -s http://localhost:3001/api/receipts | jq .
curl -s http://localhost:3001/api/batches | jq .
curl -s http://localhost:3001/api/anchors | jq .
curl -s http://localhost:3001/api/metrics | head -20
curl -s http://localhost:3001/api/withdrawals | jq .
# Public capability JSON + read-only chain/ledger paths
curl -s http://localhost:3001/api/chain/payment-settlement-capabilities | jq .
curl -s http://localhost:3001/api/da/capabilities | jq .
curl -s http://localhost:3001/api/verification/capabilities | jq .
curl -s http://localhost:3001/api/chain/status | jq .
curl -s http://localhost:3001/api/chain/blocks | jq .
curl -s 'http://localhost:3001/api/chain/blocks?witness=1' | jq .
curl -s http://localhost:3001/api/receipts | jq .
curl -s http://localhost:3001/api/batches | jq .
curl -s http://localhost:3001/api/anchors | jq .
curl -s http://localhost:3001/api/metrics | head -20
curl -s http://localhost:3001/api/withdrawals | jq .
2) Receipt 생성·전이 (INIT → AUTHORIZED → COMMITTED)2) Receipt create & transition (INIT → AUTHORIZED → COMMITTED)
# Receipt 생성 (requestId는 멱등 키)
curl -s -X POST http://localhost:3001/api/receipts \
-H "Content-Type: application/json" \
-d '{"requestId":"cli-demo-001","payload":{"amount":5000,"asset":"USDT"}}' | jq .
# 응답의 id 사용 (예: rcpt_xxx)
# 전이: INIT → AUTHORIZED (RCIPT_ID를 위 응답의 id로 교체)
curl -s -X POST http://localhost:3001/api/receipts/RCIPT_ID/transition \
-H "Content-Type: application/json" \
-d '{"status":"AUTHORIZED"}' | jq .
# 전이: AUTHORIZED → COMMITTED
curl -s -X POST http://localhost:3001/api/receipts/RCIPT_ID/transition \
-H "Content-Type: application/json" \
-d '{"status":"COMMITTED"}' | jq .
# Create receipt (requestId is the idempotency key)
curl -s -X POST http://localhost:3001/api/receipts \
-H "Content-Type: application/json" \
-d '{"requestId":"cli-demo-001","payload":{"amount":5000,"asset":"USDT"}}' | jq .
# Use returned id as RCIPT_ID (e.g. rcpt_xxx)
# Transition INIT → AUTHORIZED (replace RCIPT_ID)
curl -s -X POST http://localhost:3001/api/receipts/RCIPT_ID/transition \
-H "Content-Type: application/json" \
-d '{"status":"AUTHORIZED"}' | jq .
# Transition AUTHORIZED → COMMITTED
curl -s -X POST http://localhost:3001/api/receipts/RCIPT_ID/transition \
-H "Content-Type: application/json" \
-d '{"status":"COMMITTED"}' | jq .
3) Proof API — Receipt 증빙(batchId, payloadHash, txHash, anchorStatus)3) Proof API — receipt evidence (batchId, payloadHash, txHash, anchorStatus)
# receiptId는 조회할 Receipt의 id
curl -s http://localhost:3001/api/receipts/proof/RCIPT_ID | jq .
# Replace RCIPT_ID with the receipt id to prove
curl -s http://localhost:3001/api/receipts/proof/RCIPT_ID | jq .
4) FREEZE/AML — payload.amlFlag 또는 freeze로 FROZEN 생성4) FREEZE/AML — FROZEN via payload.amlFlag or freeze
# amlFlag: true 이면 생성 직후 FROZEN 전이
curl -s -X POST http://localhost:3001/api/receipts \
-H "Content-Type: application/json" \
-d '{"requestId":"cli-freeze-001","payload":{"amount":100,"asset":"USDC","amlFlag":true}}' | jq .
# status가 FROZEN으로 반환됨
# amlFlag: true transitions to FROZEN right after create
curl -s -X POST http://localhost:3001/api/receipts \
-H "Content-Type: application/json" \
-d '{"requestId":"cli-freeze-001","payload":{"amount":100,"asset":"USDC","amlFlag":true}}' | jq .
# Response status should be FROZEN
5) 배치 생성·앵커 (Batcher가 주기 실행. 수동으로 배치 생성)5) Batch & anchor (Batcher runs on schedule; manual batch create)
# COMMITTED Receipt가 있을 때 배치 생성 (Batcher는 30초마다 자동 실행)
curl -s -X POST http://localhost:3001/api/batches/create \
-H "Content-Type: application/json" \
-d '{}' | jq .
# 앵커 목록·검증 실행 (Batcher가 앵커 제출 후)
curl -s http://localhost:3001/api/anchors | jq .
curl -s -X POST http://localhost:3001/api/anchors/verify/run | jq .
# Create a batch when COMMITTED receipts exist (Batcher also runs ~every 30s)
curl -s -X POST http://localhost:3001/api/batches/create \
-H "Content-Type: application/json" \
-d '{}' | jq .
# List anchors and run verify job (after Batcher submits anchor)
curl -s http://localhost:3001/api/anchors | jq .
curl -s -X POST http://localhost:3001/api/anchors/verify/run | jq .
6) Withdrawal — 인출 요청·승인·실행·정산(settle)6) Withdrawal — request, approve, execute, settle
# 인출 요청 생성 (역할: system/operator 필요. RBAC 비활성 시 생략 가능)
curl -s -X POST http://localhost:3001/api/withdrawals \
-H "Content-Type: application/json" \
-d '{"receiptId":"rcpt_xxx","payload":{"amount":1000}}' | jq .
# id 확인 (예: wd_xxx). 아래 WD_ID를 이 값으로 교체
curl -s -X PATCH http://localhost:3001/api/withdrawals/WD_ID/approve | jq .
# 실행 (APPROVED → EXECUTED). Relayer가 자동 호출하거나 수동
curl -s -X PATCH http://localhost:3001/api/withdrawals/WD_ID/execute | jq .
# 정산 완료 (EXECUTED → SETTLED)
curl -s -X PATCH http://localhost:3001/api/withdrawals/WD_ID/settle | jq .
curl -s http://localhost:3001/api/withdrawals | jq .
# Create withdrawal (system/operator role if RBAC on; optional if RBAC off)
curl -s -X POST http://localhost:3001/api/withdrawals \
-H "Content-Type: application/json" \
-d '{"receiptId":"rcpt_xxx","payload":{"amount":1000}}' | jq .
# Note withdrawal id (e.g. wd_xxx); substitute WD_ID below
curl -s -X PATCH http://localhost:3001/api/withdrawals/WD_ID/approve | jq .
# Execute (APPROVED → EXECUTED); Relayer may do this automatically
curl -s -X PATCH http://localhost:3001/api/withdrawals/WD_ID/execute | jq .
# Mark settled (EXECUTED → SETTLED)
curl -s -X PATCH http://localhost:3001/api/withdrawals/WD_ID/settle | jq .
curl -s http://localhost:3001/api/withdrawals | jq .
7) 대사(Reconciliation)·정산 결과(Settlement)7) Reconciliation & settlement results
# 대사 실행 (mismatch 시 freezeOnMismatch 옵션)
curl -s -X POST http://localhost:3001/api/reconciliation/run \
-H "Content-Type: application/json" \
-d '{"freezeOnMismatch":false}' | jq .
# 정산 결과 적용 (ANCHORED → SETTLED/FAILED). rcpt_xxx를 실제 receiptId로 교체
curl -s -X POST http://localhost:3001/api/settlement-results \
-H "Content-Type: application/json" \
-d '{"items":[{"receiptId":"rcpt_xxx","provider":"demo","settlementRef":"ref-1","result":"SUCCESS"}]}' | jq .
# Run reconciliation (optional freezeOnMismatch on mismatch)
curl -s -X POST http://localhost:3001/api/reconciliation/run \
-H "Content-Type: application/json" \
-d '{"freezeOnMismatch":false}' | jq .
# Apply settlement result (ANCHORED → SETTLED/FAILED); replace rcpt_xxx
curl -s -X POST http://localhost:3001/api/settlement-results \
-H "Content-Type: application/json" \
-d '{"items":[{"receiptId":"rcpt_xxx","provider":"demo","settlementRef":"ref-1","result":"SUCCESS"}]}' | jq .
8) 정책·승인 (4-eyes, 재처리 승인)8) Policy & approvals (4-eyes, replay approval)
# 정책 설정 조회
curl -s http://localhost:3001/api/policy | jq .
# 승인 대기 목록 (POLICY_APPROVAL_AMOUNT_THRESHOLD 초과 시 Receipt 생성이 202+approvalId 반환)
curl -s http://localhost:3001/api/approvals/pending | jq .
# 승인: POST /api/approvals/:id/approve
# Fetch active policy
curl -s http://localhost:3001/api/policy | jq .
# Pending approvals (large receipts may return 202 + approvalId)
curl -s http://localhost:3001/api/approvals/pending | jq .
# Approve: POST /api/approvals/:id/approve
9) Scanner·Relayer (별도 터미널)9) Scanner & Relayer (separate terminals)
# 터미널 2: Scanner 기동 (Ledger API가 3001에서 떠 있는 상태)
npm run start:scanner
# 기본 포트 3003. http://localhost:3003/health, http://localhost:3003/api/receipts 등
# 터미널 3: Relayer 기동 (APPROVED 인출 건 자동 execute)
# PowerShell: $env:LEDGER_API_URL="http://localhost:3001"; npm run start:relayer
# bash: LEDGER_API_URL=http://localhost:3001 npm run start:relayer
# 15초마다 GET /api/withdrawals?status=APPROVED 후 PATCH execute
# Terminal 2: start Scanner (Ledger API must be on :3001)
npm run start:scanner
# Default :3003 — http://localhost:3003/health, http://localhost:3003/api/receipts, etc.
# Terminal 3: start Relayer (auto-execute APPROVED withdrawals)
# PowerShell: $env:LEDGER_API_URL="http://localhost:3001"; npm run start:relayer
# bash: LEDGER_API_URL=http://localhost:3001 npm run start:relayer
# Polls every ~15s: GET /api/withdrawals?status=APPROVED then PATCH execute
EVM 로컬 실연동: Anvil + SettlementManager 배포 후 npm run e2e:anvil-verify. OP Stack mock: npm run e2e:opstack, npm run verify:opstack-ledger. 상태 증명 포털(스텁): npm run e2e:state-proof-portal-anvil. Docker: docker build -t paychain-node . && docker run -p 3001:3001 paychain-node. Explorer(apps/explorer)에서 API Base를 http://localhost:3001/api로 두면 체인 상태·Receipt·Batch·앵커를 테이블과 상세 패널(클릭 시 JSON)로 조회할 수 있습니다. 상세는 DEVELOPER_GUIDE, TODOS_AND_NETWORK(외부 노드·네트워크) 참고.
EVM local: deploy Anvil + SettlementManager, then npm run e2e:anvil-verify. OP Stack mock: npm run e2e:opstack, npm run verify:opstack-ledger. State-proof portal (stub): npm run e2e:state-proof-portal-anvil. Docker: docker build -t paychain-node . && docker run -p 3001:3001 paychain-node. In Explorer (apps/explorer), set API base to http://localhost:3001/api to browse chain status, Receipts, Batches, and anchors. See DEVELOPER_GUIDE and TODOS_AND_NETWORK (external nodes & network).
외부 노드 참가 가능 여부External Node Participation
PayChain의 “노드”는 Ledger API + Batcher를 함께 돌리는 한 단위입니다. 동일 소프트웨어를 빌드·실행하면 외부에서도 노드를 띄워 “같은 PayChain 네트워크”에 참여할 수 있는 구조입니다. 다만 P2P 자동 발견은 없으며, 부트스트랩(공개 RPC·시드 노드 목록)과 체인 스펙은 문서화·제공 예정입니다. 원격 체인 상태 수동 조회: npm run fetch-remote-status (env: PAYCHAIN_PUBLIC_RPC_URL 또는 PAYCHAIN_SEED_URLS). 자세한 내용은 TODOS_AND_NETWORK, ARCHITECTURE(체인 가시화·노드)를 참고하세요.
A PayChain node is the combined unit of Ledger API + Batcher. Any external operator can run the same software and join the same network model. Automatic P2P discovery is not enabled yet; bootstrap endpoints (public RPC/seed list) and chain specs are documented for rollout. Manual remote status check: npm run fetch-remote-status (env: PAYCHAIN_PUBLIC_RPC_URL or PAYCHAIN_SEED_URLS). See TODOS_AND_NETWORK and ARCHITECTURE (chain visibility & nodes).
인프라·도구Infrastructure & Tooling
npm run test:full: 워크스페이스·Ledger API·Scanner·Relayer 빌드, 단위·E2E(evm/subnet/pci/opstack)·통합·Scanner 헬스·Settlement/Retry Worker mock. npm run setup-and-test로 동일 구축 후 Explorer까지 빌드.Full test — npm run test:full builds the workspace, Ledger API, Scanner, and Relayer and runs unit/E2E (evm/subnet/pci/opstack), integration, Scanner health, and settlement/retry worker mocks. npm run setup-and-test also builds Explorer.anchor-audit 병합), ID/batchId 클릭 시 상세 JSON. Ledger API 또는 Scanner URL. apps/explorerExplorer — summary cards, Receipt/Batch/anchor tables (PCI reconcile columns, public anchor-audit merge in detail), JSON on row click. Ledger API or Scanner base. apps/explorerverify/run 주기·GET /health의 pciVerifyPoller. DEVELOPER_GUIDE·services/scannerScanner — Ledger API proxy, L1 anchor ingest (EVM), optional PCI verify/run polling and pciVerifyPoller on GET /health. DEVELOPER_GUIDE, services/scannernpm run start:relayer (LEDGER_API_URL 필요).Relayer — polls APPROVED withdrawals, calls execute/settle with retries. npm run start:relayer (needs LEDGER_API_URL).npm run fetch-remote-status. 부트스트랩 URL로 GET /api/chain/status 확인.Remote chain status — npm run fetch-remote-status; GET /api/chain/status against bootstrap URLs.npm run check:network-opstack-ops, 릴리스 게이트 재현 npm run check:network-opstack-release-gateNetwork & OP checks — npm run check:network-opstack-ops; release gate repro npm run check:network-opstack-release-gatenpm run w3:import-dry-run, w3:export-snapshot, verification:challenge-http, verification:dlq:list, VERIFICATION_DLQ_ACTION=replay npm run verification:dlq:replay, 통합 npm run test:verification-stub·npm run test:integrationW3 & verification CLI — npm run w3:import-dry-run, w3:export-snapshot, verification:challenge-http, verification:dlq:list, VERIFICATION_DLQ_ACTION=replay npm run verification:dlq:replay, plus npm run test:verification-stub and npm run test:integrationnpm run start:op-batcher-bridge (OP_BRIDGE_FORWARD_URL로 실 업스트림 연결)OP HTTP bridge — npm run start:op-batcher-bridge (forward to real upstream via OP_BRIDGE_FORWARD_URL)verification.challenge.dead_letter 포함. 개발용 참조 구독: KAFKA_EVENT_FILTER=dead-letter npm run ledger-kafka-consume-reference, NATS_EVENT_FILTER=dead-letter npm run ledger-nats-subscribe-reference — DATA_AND_PROTOCOLS(Ledger 이벤트)Ledger events & brokers — optional in-process Kafka/NATS, including verification.challenge.dead_letter. Reference consumers: KAFKA_EVENT_FILTER=dead-letter npm run ledger-kafka-consume-reference, NATS_EVENT_FILTER=dead-letter npm run ledger-nats-subscribe-reference — DATA_AND_PROTOCOLS (ledger events)npm run check:state-proof-portal-readiness, npm run check:state-proof-l1-env, npm run e2e:state-proof-portal-anvil — WITHDRAWAL_AND_VERIFICATIONState-proof withdrawal (Portal) — npm run check:state-proof-portal-readiness, npm run check:state-proof-l1-env, npm run e2e:state-proof-portal-anvil — WITHDRAWAL_AND_VERIFICATION유니버설 레이어에 붙일 때 쓰는 API·패턴입니다. 결제 측은 멱등·전이·웹훅, 정산 측은 배치·앵커·Proof를 같은 Receipt ID로 이어갑니다.
APIs and patterns to integrate into the universal layer. Payment flows use idempotency/transition/webhooks, while settlement flows use batch/anchor/proof on the same Receipt ID.
GET /api/chain/payment-settlement-capabilities(통합 모델·향후 스트림 슬롯), GET /api/da/capabilities, GET /api/verification/capabilities; 에코 스텁(/api/registry/onchain/*, reputation, marketplace, micropayment)Public discovery — GET /api/chain/payment-settlement-capabilities, GET /api/da/capabilities, GET /api/verification/capabilities; ecosystem stubs (registry/on-chain, reputation, marketplace, micropayment)“PayChain은 유니버설 결제·정산 레이어다 — 레일은 다양해도 Receipt·Proof는 하나다.”
“PayChain is a universal payment & settlement layer — many rails, one Receipt and Proof.”
“캡처·승인은 오프체인/L2에서, 확정·감사 가능한 닫힘은 배치·L1 앵커로 처리한다.”
“Capture and authorize off-chain/L2; auditable finality closes with batches and L1 anchors.”
“소비자 앱이 아니라 기관·파트너용 SSOT — 멱등·정책·웹훅·Explorer까지 한 스택에 있다.”
“Institutional SSOT, not a consumer app — idempotency, policy, webhooks, and Explorer in one stack.”
은행·PG·감사가 PayChain을 운영·연동할 때 참고할 문서입니다. 기관급 프로덕션, 정식 L2/롤업, 가스비 대책, 웹2/은행 인프라 연동 체크리스트와 정책·RUNBOOK을 한곳에서 연결합니다.
Reference documents for banks, PGs, and auditors operating PayChain: institutional production readiness, L2/rollup integration, gas strategy, Web2/banking connectivity, policy and runbook.
npm run check:operational-mvp-preflightProduction, L2, gas, integration, roles · §9 network, consensus baseline, operational MVP (A–G) · offline npm run check:operational-mvp-preflightGET /api/observability/summary, Prometheus, 체인 상태 집계GET /api/observability/summary, Prometheus, chain status aggregates기관 담당자가 랜딩만 보고도 운영 가능성을 가늠할 수 있도록, 제품 안에 이미 있는 감사·관측 표면을 한 블록으로 묶었습니다.
A single block for teams who need to see auditability and ops signals without reading the whole repo first.
/api/metrics, /api/observability/summary, 공개 endpoint-readiness·네트워크 활성화 JSON. OBSERVABILITY.Observability — /api/metrics, /api/observability/summary, public readiness and activation JSON. OBSERVABILITY.PayChain은 여러 결제 레일을 붙여도 운영자는 하나의 흐름으로 통제할 수 있게 만드는 데 초점을 둡니다. 아래는 그 관점에서 본 핵심 장점입니다.
PayChain is built so teams can manage many rails through one operating flow. These are the key strengths from that perspective.
배포와 운영의 구체 명령은 랜딩보다 개발자 문서에서 보는 편이 더 정확합니다. 여기서는 제품의 장점과 사용 그림에 집중합니다.
Concrete deployment commands belong in the developer docs. The landing focuses on product value and usage picture.
처음 보는 분이라면 아래 문서만으로도 제품 구조와 연동 범위를 빠르게 파악할 수 있습니다.
If this is your first look, the links below are enough to understand the product structure and integration scope quickly.