AI 네이티브 자금 이동을 위한 원장(Ledger)

LedgerForge는 오픈 소스 복식 부기(double-entry ledger) 시스템입니다. 지갑 이체, 지급액(payouts), 청구 활동, 예약 및 환불을 정확한 정수 단위로 기록하며, 검증 가능한 감사 체인(audit chain)으로 해당 기록에 대한 이력을 보장하고, AI 에이전트가 사용하는 키를 포함하여 모든 API 키에 지출 정책을 강제합니다. HTTP API, Go 라이브러리 또는 로컬 MCP 서버를 통해 사용할 수 있습니다.

PostgreSQL은 금융 기록을 저장하며 Redis는 큐와 백그라운드 워커를 실행합니다. 검색 및 관찰 가능성(observability) 서비스는 선택 사항입니다. LedgerForge는 돈의 이동을 기록합니다. 결제 레일(payment rails) 연결과 회계 모델 정의는 애플리케이션 책임으로 남겨둡니다.

사용 사례 (Use cases)

• 지갑 및 저장 가치 (Wallets and stored value): 고객 또는 계정별 잔액, 지출 가능한 자금을 줄이는 인플라이트 홀드(inflight holds), 제한된 초과 지급액(overdrafts) 및 연결된 환불.
• 지급 및 분배 (Payouts and disbursements): 지급액이 진행 중일 때 자금을 예약하고, 레일에서 보고가 있을 때 예약을 확정하거나 취소하며, 외부 기록과 조정합니다.
• 마켓플레이스: 판매자, 수수료 및 플랫폼 잔액에 걸쳐 하나의 결제를 결정론적 할당(deterministic allocation)으로 분할하여, 각 부분이 항상 총합계와 일치하도록 합니다.
• 사용량 기반 청구 (Usage-based billing): 측정된 요금을 정확한 단위로 기록하고, 큐에 넣거나 예약하며,멱등성 참조(idempotent references)를 사용하여 안전하게 재시도합니다.
• 돈을 이동시키는 AI 에이전트: 각 에이전트에 자체 API 키와 통화 한도, 허용 목록(allowlists), 일일 예산 및 서버가 강제하는 승인 홀드(approval holds)를 부여하고, MCP 서버를 통해 에이전트를 연결합니다.

LedgerForge를 사용하는 이유 (Why LedgerForge)

• 정확한 금액 (Exact money): 정수(integer) 포스팅, 명시적인 정밀도(explicit precision) 및 결정론적 분할을 제공합니다. 회계 보증를 참조하세요.
• 검증 가능한 원장 (Verifiable ledger): 읽기 전용 ledgerforge verify가 회계 증거를 재현(replays)합니다. 버전 관리된 감사 체인과 내보내기 가능한 체크포인트는 독립적으로 보관된 루트에 대해 audit verify --anchor를 지원합니다. 커버리지 및 레거시 제한 사항은 검증 가이드를 참조하세요.
• 에이전트 안전장치 (Agent guardrails): 키별 통화 및 정밀도 한계, 잔액 및 원장 허용 목록(allowlists), 영구 일일 예약 및 승인 보류 등을 제공하며, 이는 클라이언트가 아닌 서버에 의해 강제됩니다. 위임된 키는 제한 사항을 상속하고 조상 예산을 공유합니다. MCP를 API 키에 바인딩하고 독립적인 승인자 자격 증명은 에이전트의 권한 외부에 유지하세요. 에이전트 안전성 및 실행 가능한 정책 예시를 참조하세요.
• 강화된 API (A hardened API): 소유자 바인딩 키 관리, 제약된 위임(constrained delegation), 권위 있는 취소 확인(authoritative revocation checks), 제한된 입력 및 정제된 백엔드 오류 처리를 제공합니다. 전용 웹훅 서명 비밀(webhook signing secrets)과 목적지 제어는 아웃바운드 통합을 보호합니다. 보안 운영을 참조하세요.
• 테스트된 불변성 (Tested invariants): 정확 금액 및 할당 퍼즈 타겟, 생성된 PostgreSQL 연산 시퀀스, 재무 라이프사이클 및 지출 능력 전환에 대한 잔액 보존 확인(balance conservation checks)과 레이스 테스트를 수행합니다.
• 운영 워크플로우 (Operational workflows): 진행 중인 예약(inflight reservations), 부분 정산(partial settlement), 환불(refunds), 분할 및 일괄 이체(split and bulk transfers), 조정(reconciliation), 계보(lineage), 스냅샷 및 선택적 검색, 지표(metrics) 및 OpenTelemetry를 지원합니다.
• 추적 가능한 릴리스 (Traceable releases): Linux, macOS 및 Windows용 바이너리, 다중 플랫폼 이미지, 체크섬, SPDX SBOM 및 이미지 증명서(image attestations)를 제공하며, 테스트, 취약점 및 퍼즈 게이트를 통과한 후에만 게시됩니다.

회계 보증 (Accounting guarantees)

• 정확한 금액 (Exact amounts): 전표(postings)와 잔액 산술 연산은 정수 단위(integer units)를 사용합니다. 부동 소수점 입력 손실을 방지하기 위해 precise_amount에 명시적인 precision을 지정하여 precise_amount를 공급해야 합니다. 예를 들어, 정밀도(precision)가 100인 경우 1250은 12.50을 나타냅니다.
• 복식 부기 (Double entry): 적용되는 모든 이체는 출금 계정(source)에서 해당 금액만큼 차변(debits) 처리하고, 입금 계정(destination)에서 동일한 금액만큼 대변(credits) 처리합니다. 분할된 이체(Split transfers)는 그 금액을 여러 부분으로 나누어 배분합니다.
• 불변 전표 (Immutable postings): 수정 및 환불은 연결된 거래를 생성합니다. 재무 전표와 승인된 실행 제어는 보존되며, 고객 메타데이터만 업데이트할 수 있습니다.
• 참조 기반 Idempotency: 타임아웃 후 동일한 고유 거래 reference를 재사용할 수 있습니다. 중복된 참조는 거부되고, 새로운 참조로 재시도하는 대신 원래의 결과를 조회해야 합니다.

금액 처리, 잔액 의미론(balance semantics), 비동기 거래 상태에 대한 자세한 내용은 ledger concepts를 참고하십시오.

빠른 시작: 균형 잡힌 이체 (Quickstart: a balanced transfer)

Docker와 Compose, Python 3이 필요합니다:

git clone https://github.com/devaccuracy/ledgerforge.git
cd ledgerforge
./examples/quickstart/start.sh
...

이 로컬 전용 데모는 현재 체크아웃을 빌드하고, 무작위 마스터 키를 생성하며, 마이그레이션을 실행하고 API를 127.0.0.1:5001에 바인딩합니다. 이 데모는 두 개의 USD 잔액을 생성하고 정수 단위를 사용하여 12.50을 동기적으로 전표 처리합니다. 출금 계정은 12.50의 제한된 데모 초과 인출(overdraft)을 받고, 결과는 총 차변과 대변이 각각 1250 단위인 -1250 및 1250 단위가 됩니다. 동일한 참조로 재시도할 경우 해당 잔액은 변경되지 않아야 합니다.

source: -1250 units
destination: 1250 units
total debits = total credits = 1250 units
...

docker compose -p ledgerforge-demo -f examples/quickstart/compose.yaml down 명령으로 중지합니다. 예제 가이드에는 API 페이로드, 자격 증명 및 정리(cleanup)에 대한 내용이 포함되어 있습니다. 이 자격 증명과 데이터베이스 기본값은 로컬 사용 전용이며, 서비스를 외부에 노출하기 전에 배포 가이드를 읽어보십시오.

설치 (Install)

• 릴리스 바이너리(Release binaries): GitHub Releases에서 Linux, macOS 또는 Windows용 ledgerforge와 ledgerforge-mcp를 다운로드한 후, 아카이브를 checksums.txt로 확인합니다 (sha256sum -c checksums.txt --ignore-missing).
• 컨테이너 이미지(Container image): docker pull ghcr.io/devaccuracy/ledgerforge:1.0.0. 이 이미지는 두 바이너리 모두를 포함하며, 릴리스에는 그 다이제스트와 SBOM이 나열되어 있습니다.
• 소스에서(From source): go install github.com/devaccuracy/ledgerforge/cmd/[email protected] (Go 1.26.9 이상).

ledgerforge version을 실행하여 설치된 버전을 확인한 다음, 배포 가이드를 따르고 서버를 시작하기 전에 ledgerforge migrate up을 실행합니다. 기존 데이터베이스를 업그레이드하기 전에는 무결성 업그레이드 노트를 읽어보세요.

로컬에서 게시된 이미지 실행

cp ledgerforge.example.json ledgerforge.json
# 시작하기 전에 server.secret_key를 무작위 비밀로 교체하세요.
# 예: openssl rand -hex 32
...

설정 파일은 인증을 명시적으로 활성화합니다. API 요청에는 X-LedgerForge-Key 헤더가 사용됩니다. ledgerforge.json은 비공개로 유지하고 버전 관리에서 제외하세요. :main 이미지는 테스트된 메인 브랜치 커밋을 추적하며, 프로덕션 환경에서는 LEDGERFORGE_IMAGE를 사용하여 릴리스 태그나 다이제스트를 고정해야 합니다.

오픈 소스 및 LedgerForge Cloud

이 저장소의 모든 내용은 Apache 2.0에 따라 무료로 공개된 오픈 소스입니다: 원장(ledger), 검증 및 감사 도구, 에이전트 지출 정책 및 승인, MCP 서버, 그리고 릴리스 아티팩트까지 모두 포함됩니다. 라이선스 키나 기능 게이트가 없으며, 사용자가 직접 프로덕션 환경에서 실행할 수 있습니다.

LedgerForge Cloud는 별도의 소프트웨어가 아니라 서비스입니다: 사용자 대신 동일한 오픈 소스 코어를 운영해 주는 것입니다.

문서화 (Documentation)

문서 색인에는 모든 가이드가 나열되어 있습니다. 다음부터 시작하세요:

• 개념 (Concepts): 금액(amounts), 잔액(balances) 및 거래 상태(transaction states)
• 배포 (Deployment): 비밀 정보(secrets), TLS, 한도(limits) 및 웹훅 검증(webhook verification)
• 검증 (Verification): 회계 재실행(accounting replay) 및 외부 감사 앵커링(external audit anchoring)
• 에이전트 안전성 (Agent safety): 지출 정책(spending policies) 및 독립 승인(independent approval)
• 보안 운영 (Security operations): API 키, 위임(delegation) 및 로테이션(rotation)
• MCP 서버 (MCP server): AI 에이전트를 원장과 연결
• 아키텍처 (Architecture): 패키지 레이아웃 및 신뢰 경계(trust boundaries)

온라인 문서는 ledgerforge.io/docs에서 확인할 수 있습니다.
로드맵 (roadmap)에서는 계획된 내용을 설명하며,
변경 로그 (changelog)에는 배포된 내용이 기록되어 있습니다.

개발 (Development)

make verify
make test-integration
make vuln
...

CONTRIBUTING.md에는 전제 조건(prerequisites), 격리 통합 테스트(isolated integration tests) 및 풀 리퀘스트 기대 사항(pull request expectations)이 포함되어 있습니다.

커뮤니티, 지원 및 라이선스 (Community, support and license)

• 버그 및 제안: 이슈 양식을 사용하세요.
• 질문: 먼저 문서화를 확인하고, 도움이 되지 않으면 질문을 여세요. SUPPORT.md에는 커뮤니티 및 상업적 지원에 대한 내용이 포함되어 있습니다.
• 기여 (Contributing): CONTRIBUTING.md를 읽고 행동 강령 (Code of Conduct)을 따르세요. GOVERNANCE.md에는 의사 결정 방식이 설명되어 있습니다.
• 보안: 취약점은 [email protected]로 비공개 보고하고, 보안 정책 (security policy)을 참고하세요.

본 라이선스는 Apache 2.0에 따라 부여됩니다. 필요한 고지 사항은 NOTICE.md를 참조하십시오.