Usage manual

How to run Medusa Ledger Core locally, append events, seal blocks, and verify the chain. This manual describes the OSS API surface (v0.1).

1. Install / Docker

Requirements: Docker Desktop (or Docker Engine + Compose).

git clone https://github.com/wbsckt3/medusa-ledger.git
cd medusa-ledger
docker compose up

Expected local ports (v0.1):

http://localhost:8080/api — HTTP API
http://localhost:8080/api/verify — chain integrity

Core v0.1 lives on branch main of this repository. Commercial Cloud demo: medusa-ledger-business.

2. API reference

POST /api/events

Append a business event to the pending pool (idempotent by eventId when provided).

curl -X POST http://localhost:8080/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "pay-001",
    "eventType": "PAYMENT_CAPTURED",
    "amount": 50000,
    "currency": "COP",
    "actors": ["customer","operator"],
    "payload": { "invoice": "INV-9" }
  }'

POST /api/seal

Seal pending transactions into the next SHA-256 block linked to previousHash.

curl -X POST http://localhost:8080/api/seal \
  -H "Content-Type: application/json" \
  -d '{ "maxTx": 100 }'

GET /api/blocks

curl "http://localhost:8080/api/blocks?limit=40"

GET /api/verify

curl http://localhost:8080/api/verify

Response shape:

{
  "valid": true,
  "blocks": 3,
  "error": null,
  "at": null
}

3. Block & transaction model

Same Savjee-like ideas used in the P2L Cloud adapter (medusaChainService): genesis block, pending txs, seal with previous hash, no PoW.

Concept	Meaning
Transaction	Business event + `payloadHash` (SHA-256 of stable JSON)
Pending	Tx not yet sealed into a block
Block	`index`, `timestamp`, `previousHash`, list of tx hashes, `hash`
Genesis	Block `index = 0`, `previousHash = "0"`
Append-only	No updates/deletes of sealed history in Core

Block hash input

index|ISO_timestamp|previousHash|txHash1,txHash2,...

Then SHA-256 hex digest.

4. Verify chain

Load blocks ordered by index.
Check genesis previousHash.
Recompute each block hash; compare to stored hash.
Ensure block[n].previousHash === block[n-1].hash.

Any tampered payload or reordered link fails verify — that is the trust proof.

5. OSS limits vs Cloud

Medusa Core (OSS)	Medusa Cloud
Single ledger per instance	Multi-tenant / white-label ledgers
Generic events API	Payment gateway anchors (e.g. ePayco)
Basic verify / seal	Analytics hubs, admin keys, realtime rooms
Self-hosted Docker	Hosting, SLA, backups, compliance tooling
No ERP connectors bundled	ERP / BI / AI consumers as product

Cloud product landing: medusa-ledger-business

6. License & Sponsors

License: Apache-2.0
Sponsors: github.com/sponsors/wbsckt3
Npm scope: @medusa-ledger/* (avoids clash with Medusa e-commerce)