Web Ledgers provide a standardized method for mapping Uniform Resource Identifiers (URIs) to numerical balances on the web, enabling distributed ledger systems that transcend platform boundaries. This specification defines data models, serialization formats, and interoperability guidelines for creating decentralized economic systems using web-native identifiers.
By utilizing URIs as universal identifiers, Web Ledgers enable seamless value transfer between heterogeneous systems including social platforms, blockchain networks, communication protocols, and decentralized identity systems. The specification supports multiple serialization formats (JSON) and provides extensible entry types for different use cases.
This document defines the core data model, JSON Schema validation rules, and provides comprehensive examples demonstrating interoperability across platforms including Nostr, WebID, traditional web services, and cryptocurrency systems.
This document is an informal draft being discussed in the W3C Web Payments Community Group. It is not a W3C Standard nor is it on the W3C Standards Track.
This is a living document that may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
Comments and feedback on this specification are welcome and should be directed to the GitHub issues for this specification.
Introduction
The modern web consists of numerous independent platforms and services, each maintaining their own user accounts and value systems. Traditional ledgers, in their simplest form, consist of two columns: an identifier for an agent and their corresponding balance. Web Ledgers extend this concept to the web scale by utilizing [[RFC3986]] Uniform Resource Identifiers (URIs) as universal identifiers that transcend platform boundaries.
This specification defines a standardized approach for representing and exchanging balance information across heterogeneous systems including social networks, blockchain platforms, communication protocols, and decentralized identity systems. By leveraging web standards and providing multiple serialization formats, Web Ledgers enable interoperability between previously incompatible systems.
The Web Ledgers specification provides:
- A core data model for representing URI-to-balance mappings
- JSON-LD based serialization format
- Flexible amount formats supporting single or multi-currency entries
- Interoperability guidelines for cross-platform integration
Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [[RFC2119]].
Design Goals
Web Ledgers are a component of larger systems, such as the Linked Data ecosystem [[LINKED-DATA]], which have driven the design goals for this specification. This section summarizes the primary design goals for this specification.
Terminology
Terminology
- Web Ledger
- A structured data format that maps URIs to numerical balance values, optionally including a human-readable name and description. A Web Ledger enables interoperability between different systems by using web-native identifiers.
- Agent
- An Agent is a URI that denotes a person, machine or account on the web.
- balance
- Each URI maps to a balance in the Web Ledger. A balance is a numerical value with an explicit or implicit unit of currency. If not unit is stated the unit MAY be taken from the popular electronic coin, bitcoin, and is equal to 1 satoshi.
- currency
- A currency is denomination of a given balance
- Ledger Name
- A human-readable string that identifies a Web Ledger. The name provides a friendly identifier that helps users and systems distinguish between different ledgers.
- decentralized system
- A system in which lower level components operate on local information to accomplish global goals. For example, an ant colony is a decentralized system as there is no central control determining when food must be collected or how new tunnels should be excavated.
Data Model
The Web Ledgers data model uses JSON-LD as its primary serialization format, designed to have varying layers of complexity depending on the use case.JSON / JSON-LD
A structured JSON format for a ledger consists of an entries array with metadata and typed entries. The ledger can include a human-readable name and description to provide context about its purpose and contents. The amount field supports both simple string values (for single currency) and arrays of currency objects (for multi-currency entries).
{
"@context": "https://w3id.org/webledgers",
"type": "WebLedger",
"id": "https://example.com/ledger/1",
"name": "WebLedgers Example",
"description": "A ledger tracking balances across multiple platforms",
"created": 1705316200,
"updated": 1705316200,
"defaultCurrency": "satoshi",
"entries": [
{
"type": "Entry",
"url": "did:nostr:de7ecd1e2976a6adb2ffa5f4db81a7d812c8bb6698aa00dcf1e76adb55efd645",
"amount": "132500"
},
{
"type": "Entry",
"url": "https://www.w3.org/People/Berners-Lee/card#i",
"amount": "100000"
}
]
}
Entry Variations
All entries use the same "Entry" type but can have different properties depending on their purpose. The amount field can be either a simple string (for single currency in default denomination) or an array of currency objects (for multi-currency entries):
{
"@context": "https://w3id.org/webledgers",
"type": "WebLedger",
"id": "https://gaming.example.com/ledger/tournament",
"name": "Gaming Tournament Rewards",
"description": "Prize distribution ledger for esports tournament participants",
"defaultCurrency": "satoshi",
"entries": [
{
"type": "Entry",
"url": "did:nostr:de7ecd1e2976a6adb2ffa5f4db81a7d812c8bb6698aa00dcf1e76adb55efd645",
"amount": "132500"
},
{
"type": "Entry",
"url": "https://www.w3.org/People/Berners-Lee/card#i",
"amount": [
{"currency": "satoshi", "value": "50000"},
{"currency": "USD", "value": "25.00"}
]
},
{
"type": "Entry",
"url": "urn:voucher:1234567890abcdef",
"amount": [
{"currency": "points", "value": "100"}
]
}
]
}
Amount Serialization Rules
The amount field supports flexible serialization based on the currency context:
-
Simple string format: Use when there is exactly one
balance in the ledger's defaultCurrency. Example:
"amount": "100000" -
Array format: Use when there are multiple currencies
or when the currency differs from the defaultCurrency. Example:
"amount": [{"currency": "USD", "value": "25.00"}]
Named Ledger Use Cases
Web Ledgers can use descriptive names to clarify their purpose and context:
Community Reputation System
{
"@context": "https://w3id.org/webledgers",
"type": "WebLedger",
"id": "https://community.example.com/reputation",
"name": "Developer Community Reputation",
"description": "Reputation scores for open source contributors based on code contributions and peer reviews",
"defaultCurrency": "reputation-points",
"entries": [
{
"type": "Entry",
"url": "https://github.com/alice-dev#this",
"amount": "2750"
}
]
}
Educational Achievement Tracking
{
"@context": "https://w3id.org/webledgers",
"type": "WebLedger",
"id": "https://university.example.edu/course-credits",
"name": "Computer Science Course Credits",
"description": "Academic credit tracking for CS degree program students",
"defaultCurrency": "credit-hours",
"entries": [
{
"type": "Entry",
"url": "mailto:student@university.example.edu",
"amount": "120"
}
]
}
Security Considerations
Web Ledgers implementations SHOULD consider the following security aspects:
Authentication and Authorization
Implementations SHOULD provide mechanisms to authenticate ledger updates and authorize balance modifications. Without proper authentication, malicious actors could manipulate balances or create fraudulent entries.
Recommended approaches include:
- Digital signatures using cryptographic key pairs
- OAuth 2.0 or similar authentication protocols
- Multi-signature schemes for high-value transactions
Data Integrity
Implementations SHOULD implement mechanisms to ensure data integrity and prevent tampering. This includes:
- Cryptographic hashing of ledger entries
- Merkle tree structures for efficient verification
- Timestamp validation to prevent replay attacks
Transport Security
All ledger data transmission MUST occur over secure channels (HTTPS/TLS) to prevent man-in-the-middle attacks and ensure confidentiality.
Privacy Considerations
Web Ledgers may contain sensitive financial information. Implementations SHOULD consider the following privacy aspects:
Data Minimization
Implementations SHOULD only store and transmit the minimum amount of information necessary for ledger functionality. Sensitive metadata should be avoided unless essential.
URI Privacy
URIs used as identifiers may reveal personal information. Implementations SHOULD:
- Support pseudonymous identifiers where possible
- Provide mechanisms for identifier rotation
- Clearly document any privacy implications of URI schemes
Access Control
Implementations MUST provide appropriate access controls to prevent unauthorized access to balance information. This includes:
- Role-based access control (RBAC)
- Fine-grained permissions for different operations
- Audit logging for compliance and monitoring
Implementations
This section is informative and provides guidance for implementers of Web Ledgers systems.
Reference Implementation
A reference implementation is available at https://github.com/solidpayorg/webledgers-reference.
Known Implementations
The following implementations are known to support Web Ledgers:
- SolidPay Ledger Service - Production implementation supporting multiple URI schemes
- Nostr Ledger Extension - Experimental implementation for Nostr protocol
Examples
Decentralized Identifiers
Nostr DID
Nostr public keys represented as DIDs for decentralized social networking.
{
"type": "Entry",
"url": "did:nostr:de7ecd1e2976a6adb2ffa5f4db81a7d812c8bb6698aa00dcf1e76adb55efd645",
"amount": "132500"
}
WebID
A WebID representing a person's web identity.
{
"type": "Entry",
"url": "https://www.w3.org/People/Berners-Lee/card#i",
"amount": "100000"
}
Social Platforms
GitHub
The popular git service platform.
{
"type": "Entry",
"url": "https://github.com/solid-pay#this",
"amount": "75000"
}
Twitter/X
The microblogging service.
{
"type": "Entry",
"url": "https://x.com/user#this",
"amount": "50000"
}
YouTube
The video sharing platform.
{
"type": "Entry",
"url": "https://www.youtube.com/channel/UCabcdef1234567890#this",
"amount": "25000"
}
Communication Protocols
Traditional email addresses as identifiers.
{
"type": "Entry",
"url": "mailto:timbl@w3.org",
"amount": "15000"
}
Mobile Phone
Phone numbers as global identifiers.
{
"type": "Entry",
"url": "tel:+15550909090",
"amount": "10000"
}
Cryptocurrency & Blockchain
Bitcoin Address
Bitcoin addresses as payment identifiers.
{
"type": "Entry",
"url": "bitcoin:1Kr6QSydW9bFQG1mXiPNNu6WpJGmUa9i1g",
"amount": "2100000"
}
Transaction Outputs
Bitcoin transaction outputs (UTXOs) as specific balance holders.
{
"type": "Entry",
"url": "txo:btc:f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16:0",
"amount": "5000000000"
}
Vouchers & Tokens
Web Voucher
Digital vouchers following the webvoucher specification.
{
"type": "Entry",
"url": "urn:voucher:1234567890abcdef",
"amount": "25000"
}
Complete Ledger Example
A complete ledger with multiple entry variations demonstrating the full data model with descriptive naming for clarity, including both simple string amounts and multi-currency arrays.
{
"@context": "https://w3id.org/webledgers",
"type": "WebLedger",
"id": "https://example.com/ledger/global",
"name": "Universal Web Credits",
"description": "Cross-platform ledger demonstrating interoperability between social networks, blockchain systems, and communication protocols",
"created": 1705276800,
"updated": 1705316200,
"defaultCurrency": "satoshi",
"entries": [
{
"type": "Entry",
"url": "did:nostr:de7ecd1e2976a6adb2ffa5f4db81a7d812c8bb6698aa00dcf1e76adb55efd645",
"amount": "132500"
},
{
"type": "Entry",
"url": "https://www.w3.org/People/Berners-Lee/card#i",
"amount": [
{"currency": "satoshi", "value": "100000"},
{"currency": "USD", "value": "50.00"},
{"currency": "reputation-points", "value": "500"}
]
},
{
"type": "Entry",
"url": "https://github.com/solid-pay#this",
"amount": "75000"
},
{
"type": "Entry",
"url": "mailto:timbl@w3.org",
"amount": [
{"currency": "EUR", "value": "12.50"}
]
},
{
"type": "Entry",
"url": "urn:voucher:1234567890abcdef",
"amount": "25000"
}
]
}
Acknowledgements
The editor would like to thank the W3C Web Payments Community Group for their support and feedback during the development of this specification.
Special thanks to the following individuals and organizations for their contributions, feedback, and implementation efforts:
- The W3C Web Payments Community Group participants
- The Nostr protocol development community
- The Solid project community
- Contributors to the SolidPay project
This specification builds upon the foundational work of the World Wide Web Consortium, particularly the URI specification [[RFC3986]] and the JSON-LD specification [[JSON-LD11]].