Data Modeling

Data Format

WebWallet uses JSON-based data structures to represent transactions requests and records, along with cryptographic hashes and digital signatures to secure them. It borrows some structures and naming conventions from the JavaScript Object Signing and Encryption specifications (JWS, JWT), but it does not comply with the standards.

Record integrity is accomplished by including a hash of the record data in tamper-evident data structures along with other hashes. Message authenticity is verified by checking that the signatures on the hash of the data listed in sigs are valid. Unsecured metadata can be added to the meta property without affecting the integrity of a record.

{
  "hash": { /*cryptographic hash*/
    "alg": "hash-algorithm", // "sha256"
    "typ": "hash-type",      // "twice"
    "val": "hash-value"      // "09af..."
  },
  "data": { /*to be hashed*/
    /*key-value pairs */
  },
  "meta": { /*not hashed*/
    /*key-value pairs*/    
  },
  "sigs": [ /*cryptographic signatures*/
    {
      "alg": "signature-algorithm", // "ed25519"
      "sig": "signature-value",     // "3045..."
      "key": "public-key-value",    // "03C7..."
      "kid": "public-key-index",    // used with 'wid'
      "wid": "webwallet-address",   // used with 'kid'
      "uri": "webwallet-domain"     // "webwallet.org"
    }
  ]
}

#Data Structures

Transactions

Transaction Inputs - IOUs

WebWallet IOUs are instructions for transferring currency units in a transaction. The instructions include the domain in which the IOU can be cleared (iss), the source (sub) and possible destinations of the transaction (aud), the transaction amount (amt), the currency of the IOU (cur) and a nonce for detecting replay attacks (nce).

{
  "hash": {/*alg,typ,val*/},
  "data": {
    "iss": "issued-in",  // issuer domain        "wallet.example.com"
    "sub": "subject",    // issuer address       "wAliceAddress123"
    "aud": "audience",   // authorized claimers  "wBobAddress456"
    "amt": "amount",     // units to transfer    "50.00000000001"
    "alw": "allowance",  // credit to grant      "21000000"
    "cur": "currency",   // unit identifier      "AbCdE12345"
    "nce": "nonce",      // for replay attacks   "9876543210"
    "ref": "reference",  // custom info          "foo-bar-baz"
    "iat": "issued-at",  // creation date        "2008-10-31T00:00:00.000Z"
    "nbf": "not-before", // valid from           "2009-01-03T00:00:00.000Z"
    "exp": "expires"     // valid until          "2140-05-07T12:00:00.000Z"
  },
  "sigs": [/*signatures*/]
}

Transaction Requests

Transaction Records

{
  "hash": {/*alg,typ,val*/},
  "data": {
    "amounts": {
      "currencyCode": "transactedAmount"
    },
    "credit": {
      "currencyCode": "creditVariation"
    },
    "easing": {
      "currencyCode": "supplyVariation"
    },
    "config": {
      // pointer to previous, or [configs]
    },
    "inputs": [
      // IOUs (min: 1)
    ],
    "outputs": [
      // (min: 2)
    ]
  },
  "sigs": [/*signatures*/]
}

Transaction Outputs - Address State

{
  "_tx": 0, // count
  "adr": "address",
  "amt": "amount",
  "bal": "balance",
  "cur": "currency",
  "lim": {
    "low": "lower-limit",
    "upp": "upper-limit"
  },
  "pre": {
    "idx": "previous-output-index",
    "txn": "previous-transaction"
  }
}

Statements

Blocks

Trees