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:

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.

Goal Description
Simplicity The ledger is designed to be as simple as possible. As such you just need two data points. The user and the balance.
Decentralization The ledger should not be server specific, though it may be.
Security Transmission of a ledger changes tend to be over encrypted channels.
Discoverability It may be possible to discover more information about a URI by standard mechanisms of dereferencing, including, but not limited to HTTP.
Interoperability URIs are used to provide wide interoperability with existing systems on the web.
Portability Be system and network-independent and enable entities to use their digital identifiers with any system that supports Web Ledgers.
Extensibility When possible, enable extensibility provided it does not greatly hinder interoperability, portability, or simplicity.

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:

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:

Data Integrity

Implementations SHOULD implement mechanisms to ensure data integrity and prevent tampering. This includes:

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:

Access Control

Implementations MUST provide appropriate access controls to prevent unauthorized access to balance information. This includes:

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:

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

Email

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:

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]].