Overview & Core Value Proposition
Ledgerly is a privacy-first financial infrastructure protocol designed for on-chain businesses. Submitted to NEAR Hackathon under the realworld (Bring the boring money onchain) and privacy (Selective disclosure & confidential onchain financial infrastructure) tracks.
Commercial invoices, itemized descriptions, counterparty contact details, and banking metadata are encrypted via authenticated AES-256-GCM. Zero raw business information leaks to public block explorers.
Only a random 32-byte opaque escrow identifier and a tamper-evident commitment hash (sha256(canonicalJSON(payload) || salt)) are anchored to the NEAR smart contract.
Privacy & Envelope Encryption (AD-3)
Ledgerly uses off-chain envelope encryption combined with scoped asymmetric view keys (X25519) to allow certified auditors to verify financial records without exposing customer data to the world.
Commitment Calculation Formula
Every invoice and remittance is transformed into a deterministic canonical JSON string, concatenated with a 32-byte cryptographic salt, and hashed via SHA-256 before contract deposit:
const canonical = canonicalJson({
id: "req_9f8e7d6c",
orderRef: "INV-2026-001",
amountDecimal: "680.00",
currency: "USDC",
customerEmail: "finance@partner.example"
});
// 32-byte high-entropy salt prevents dictionary & rainbow table attacks
const commitment = crypto.createHash("sha256")
.update(Buffer.concat([Buffer.from(canonical, "utf8"), saltBytes]))
.digest("hex");Auditor Scoped View Keys
Merchants can issue time-limited, scoped view keys to authorized auditors. The auditor accesses the /app/auditor console, loads the encrypted envelope, and decrypts it using their key grant. The system re-hashes the decrypted payload and verifies that it matches the on-chain commitment anchored on NEAR Testnet.
Smart Escrow on NEAR Testnet (AD-1 & AD-2)
Built in Rust using near-sdk and deployed on NEAR Testnet. Funds are held autonomously by the contract rather than in custodial bank accounts.
If a buyer sends 700 USDC for a 680 USDC invoice, the escrow contract releases 680 USDC to the merchant and automatically refunds the 20 USDC excess to the buyer in the exact same transaction.
If an invoice expires without completion, the buyer can call claim_refund directly on the contract to reclaim their tokens, even if the Ledgerly backend is offline or unreachable.
Developer REST API (AD-10)
Integrate Ledgerly into your billing, ERP, or e-commerce workflow using idempotent JSON endpoints hosted on our live production environment.
1. Create Non-Custodial Invoice (Payment Request)
Issues an idempotent escrow payment request. Encrypts sensitive metadata off-chain and anchors the cryptographic commitment to NEAR testnet.
curl -X POST https://tryledgerly.up.railway.app/api/v1/actions \
-H "Content-Type: application/json" \
-d '{
"action": "CREATE_PAYMENT_REQUEST",
"orderRef": "INV-2026-088",
"amountDecimal": "250.00",
"customerEmail": "billing@client.com"
}'{
"ok": true,
"action": "CREATE_PAYMENT_REQUEST",
"result": {
"id": "pr_a1b2c3d4",
"orderRef": "INV-2026-088",
"amountDecimal": "250.00",
"currency": "USDC",
"status": "OPEN",
"escrowId": "e738c4ab...24ef",
"commitment": "8f4a13b6...99c2",
"checkoutUrl": "https://tryledgerly.up.railway.app/checkout/pr_a1b2c3d4"
}
}2. Query Live Protocol State
Fetches active escrow invoices, cross-border remittances, settled totals, verified accounting entries, and network configuration.
curl -X GET https://tryledgerly.up.railway.app/api/v1/state{
"ok": true,
"state": {
"network": "testnet",
"escrowContractId": "ledgerly-escrow-9e70f9ea.testnet",
"usdcContractId": "ledgerly-usdc-a627a4c0.testnet",
"totalSettledUsdc": "11,110.00",
"varianceInvariant": "0.00",
"paymentRequestsCount": 4,
"remittancesCount": 3
}
}3. System Health & Worker Heartbeats
Validates persistent SQLite storage, live NEAR RPC endpoint availability, and background reconciliation worker health.
curl -X GET https://tryledgerly.up.railway.app/api/health{
"status": "ok",
"runtimeMode": "NEAR_TESTNET_RPC",
"db": "ok",
"rpc": "reachable",
"workers": {
"running": true,
"heartbeatAgesMs": {
"indexer": 1240,
"reconciliation": 1238
}
}
}4. Fund USDC from Testnet Faucet
Mints 500.00 NEP-141 Testnet USDC directly to any target testnet account for end-to-end integration testing.
curl -X POST https://tryledgerly.up.railway.app/api/v1/actions \
-H "Content-Type: application/json" \
-d '{
"action": "FAUCET_USDC",
"accountId": "your-account.testnet"
}'Verifiable Double-Entry Accounting (AD-5)
Every business event automatically writes mathematical double-entry journal legs stored in integer minor units (bigint), guaranteeing a $0.00 net variance invariant (Σ debits == Σ credits).
Both the merchant console and the auditor portal feature one-click CSV ledger export, formatted for standard accounting software with account codes, debit/credit columns, and transaction hash anchors.
Threat Model & Security Roadmap
Comprehensive security posture and key custody boundary analysis.
- Public chain observers and competitors sniffing financial volumes.
- Dictionary attacks via high-entropy 32-byte salts per payload.
- Passive tampering of off-chain database records detected via hash mismatch.
- Proposal A: Master-Key AES-256-GCM encryption at rest via external KMS (Vault/AWS/GCP).
- Proposal B: Client-side browser-based WebCrypto auditor key generation.
- Proposal C: Confidential Computing inside TEE (Intel SGX / AMD SEV).