• Reading the docs…
Start trading

API reference

Ledger leaves and proofs

The Ledger’s two public reads: the current leaves at the tree positions an account’s sealed status names, each with its Merkle path, and each Commit’s diff for history. Every caller gets the same answer to the same request, and neither route takes an owner or an account.

Routes#

POST /v1/ledger/leaves#

The current encrypted leaves at up to 256 tree positions, each with its Merkle path to one verified root. Balances are read here, with no diff scanned: readBalances sends the positions the account’s sealed status reply names, pinned to the root it read from the program’s LedgerRoot account through the RPC relay, and checks every leaf against that root before it decrypts its own (Reading your own balances).

The body is LedgerLeavesRequest: tree positions and a root, both public, with nothing that names an account. Returns LedgerLeaves.

  • A request holds at most 256 positions, each from 0 to 4,294,967,295, and a position sent twice is answered once. Read more positions in requests of 256 pinned to the same root.
  • root is one of the latest four verified roots, or a root the chain has committed since, which the API answers once every path checks out against it. Without root, the answer is at the latest verified root.
  • Each requested position comes back in leaves or in missing, and assets describes the assets the returned balance leaves name.

Check the answer against the chain, as readBalances does:

  1. Read LedgerRoot through the relay with readLedgerRoot, and send its root. The answer’s root, crossing and slot must equal the account’s root, k and last_commit_slot.
  2. Each leaf’s path.index must equal its position, and its path must lead to root (MerklePath).
  3. A balance leaf, whose first byte is 2, names its asset by Registry index (Leaf); assets must hold that registryIndex, admitted.
  4. For an account’s own positions, missing is empty: every position its status names holds a leaf at that root.

A Commit can land between reading LedgerRoot and sending the request. While the root is among the latest four the answer is unchanged; once it has left them, the route answers INDEXER_UNAVAILABLE with fieldErrors.root ["snapshot_changed"]. Read the status and LedgerRoot again and resend, as readBalances does once.

Errors

  • UNSUPPORTED_MEDIA_TYPE: the body is not application/json.
  • VALIDATION_ERROR: the body is not JSON, positions is missing, holds more than 256 entries or one that is not an integer from 0 to 4,294,967,295, root is not base64 of 32 bytes, or the body carries another key.
  • INDEXER_UNAVAILABLE with fieldErrors.root ["snapshot_changed"]: root is neither among the latest four verified roots nor a newer committed root the API can answer, or the recent roots are still being prepared after a Commit. Read LedgerRoot again and resend; retryable.
  • INDEXER_UNAVAILABLE without fieldErrors: the indexer holds no verified snapshot, because it has not verified the latest Commit yet or its root disagrees with the chain, or an asset a returned leaf names is not indexed yet. Keep the last verified balances and retry; retryable.
  • MERKLE_PROOF_INVALID: for a root newer than the API’s index, the leaves gathered for it failed the API’s check: a path that does not reach the root, a position not requested or left out, or asset details that differ from the admitted asset’s.
  • RATE_LIMITED: more than 600 leaf reads in a minute from this client, with retryAfterSeconds. Leaf reads do not count toward the 60 POST requests a minute of the other /v1 routes.
TypeScript
import { readLedgerRoot, unb64, verifyMerklePath } from '@privium/sdk'

const status = await privium.openOrders()
const onChain = await readLedgerRoot(api, privium.config.programId)
const page = await api.ledgerLeaves({ positions: status.ledger.positions.slice(0, 256), root: onChain.root })

if (page.crossing !== onChain.crossing || page.slot !== onChain.slot) throw new Error('The answer is not at the on-chain root.')
for (const leaf of page.leaves) {
  const reaches = leaf.path.index === leaf.position && verifyMerklePath(unb64(leaf.bytes), leaf.position, leaf.path.siblings.map(unb64), unb64(onChain.root))
  if (!reaches) throw new Error(`The path of position ${leaf.position} does not reach the root.`)
}

The request named a position Crossing 45 wrote and one it cleared, pinned to Crossing 45’s root, then the latest committed. The capture keeps two of the leaf’s 32 siblings.

Response
{
  "root": "qrSL1YE+I6XnznRAuEEDtSHRn86QKBQXz9UWpzcCBCM=",
  "crossing": "45",
  "slot": "470449032",
  "leaves": [
    {
      "position": 129687632,
      "bytes": "AgAAAAAtAAAAAAAAANZ9dx5VH8HZIh6khmfp+SKao/QvgvtR0141KfncHqqzgt5k1cvqQbTKtWlHgkrhVB8Oa9y0v6liut12gYnHEDri6avYp0YoIh8RZQsv2Za90a0LMn8Z2dfbGwMi7sYqUiMl5n6xRDB2CWMToPILi/gF6Xf3N3IjvtVtJGW1rjJ3HM1P/FYpYmT1hsaVX49v5m1qQQKiRfvMVNS6exiMRl8idj7thQHTfi7l9NJrMvWSQxqMpwvIKZlVjYnri3+AuZl7cMXuJrfV06rtQB0OcEbsmvRo",
      "path": {
        "index": 129687632,
        "siblings": [
          "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
          "/kPWavpKmlxPnJ2on0/7UmNcjzQuf/tzHWjjbFmCByo="
        ]
      }
    }
  ],
  "missing": [
    29803735
  ],
  "assets": [
    {
      "mint": "So11111111111111111111111111111111111111112",
      "symbol": "SOL",
      "name": "Solana",
      "decimals": 9,
      "icon": null,
      "tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      "admitted": true,
      "registryIndex": 0,
      "denominationUnit": "10000000"
    }
  ]
}

GET /v1/ledger/diffs#

Pages through committed Ledger diffs in order, from a public cursor: every diff, a span of Crossings, or a list of them. readHistory reads it for the Account page’s history and readBundle for a viewing bundle at /v, each fetching only the diffs of the Crossings that hold the entries it reads, and each reader decrypts only the entries its own keys open. During an Escape, recoverBalancesFromHistory reads every diff up to the frozen root to rebuild balances without a status reply.

Parameter Type In Meaning
crossings string (optional) query Read only the diffs of these Crossings: 1 to 256 distinct indices, separated by commas. A listed Crossing with no committed diff is left out.
cursor string (optional) query Read the diffs of the Crossings after this index: the previous page's nextCursor. Omit it to scan from the start.
fromCrossing string (optional) query Read only the diffs of Crossings at or after this index.
toCrossing string (optional) query Read only the diffs of Crossings at or before this index. hasMore is false once a page reaches it.
limit integer (optional) query, default 24 Diffs per page, 1 to 100. A page also ends before 2 MiB of diffs.

Returns LedgerDiffs.

fromCrossing and toCrossing bound the scan to the Crossings from one to the other, both included, and cursor stays the exclusive start within them. A page’s hasMore is false once it reaches toCrossing, so a period reads as its own short scan: send both bounds, then each nextCursor while hasMore is true. A span with fromCrossing above toCrossing answers an empty page.

crossings lists the Crossings to read, 1 to 256 distinct indices separated by commas, and the scan reads only their diffs, still after cursor, within the bounds and oldest first. readHistory sends the Crossings its account’s sealed status names for the range as history.entryCrossings (AccountStatus), and readBundle the Crossings of the ranges a viewing bundle carries. A listed Crossing with no committed diff is left out of the page, so compare the page’s Crossings with the list.

Check each diff against the chain before using it, as the SDK does:

  1. Read its root with GET /v1/roots/{root}. The answer’s root, crossing and programId must match the diff and the program.
  2. Pin that answer to the chain: read its commitTransaction through the RPC relay with getTransaction. The transaction must have succeeded at the answer’s slot and hold the program’s commit for this Crossing, right after the Ed25519 check of the enclave’s signed Commit message, which names the program, the Crossing, root and diffHash; the signature must verify.
  3. Join chunks: they must equal bytes and fold to that answer’s diffHash (Data availability through log_diff).
  4. Decode bytes. Its header’s root, previous root and Crossing must match the diff’s, and each diff’s previousRoot must be the root of the one before it.
  5. Each balance leaf the diff writes must equal its entry in leaves, whose path leads to root.

A page holds up to limit diffs and stops before 2 MiB of them, so it can hold fewer; a diff larger than that fills a page alone. Send nextCursor as the next cursor while hasMore is true. Once it is false on a scan with no toCrossing, the scan is current: send the same nextCursor later, or follow ledger events on the stream (Events).

Errors

  • VALIDATION_ERROR: cursor, fromCrossing or toCrossing is not an unsigned integer, crossings is not 1 to 256 distinct unsigned integers separated by commas, limit is outside 1 to 100, or the query carries another key.
  • INDEXER_UNAVAILABLE: the indexer has not verified the latest Commit yet, or its root disagrees with the chain, or the paths of a diff on the page are still being filled in. Keep the last verified history, marked as of its Crossing, and retry; retryable.
  • PROGRAM_UNAVAILABLE: the Pool is not indexed yet; retryable.
TypeScript
// The Crossings an account's status names as holding its entries.
const wanted = ['5', '8', '14']

let cursor: string | undefined
let hasMore = true
while (hasMore) {
  const page = await api.ledgerDiffs({ crossings: wanted.join(','), cursor, limit: 1 })
  for (const diff of page.items) {
    const anchor = await api.root(diff.root)
    if (anchor.crossing !== diff.crossing) throw new Error('The diff root does not match its Commit.')
  }
  cursor = page.nextCursor
  hasMore = page.hasMore
}

The capture is the first page of Crossings 5, 8 and 14: the diff of Crossing 5, with hasMore true for the two after it. It keeps the first of the diff’s 10 chunks, of its 130 leaves and of its 124 clearedPositions, and two of that leaf’s 32 siblings; bytes, the whole diff, is cut to its first 96 characters.

Response
{
  "items": [
    {
      "cursor": "5",
      "crossing": "5",
      "previousRoot": "Hne60ab7+Jz5x3SUqClGwUuTqV9kaIgy7/sP2lypJZs=",
      "root": "WJdpkmI5SNMf+kF81oKvpl2lh885wF1igRrBVxL0t2M=",
      "slot": "470448248",
      "bytes": "UFZEMQUAAAAAAAAAHne60ab7+Jz5x3SUqClGwUuTqV9kaIgy7/sP2lypJZtYl2mSYjlI0x/6QXzWgq+mXaWHzznAXWKBGsFX…",
      "chunks": [
        "UFZEMQUAAAAAAAAAHne60ab7+Jz5x3SUqClGwUuTqV9kaIgy7/sP2lypJZtYl2mSYjlI0x/6QXzWgq+mXaWHzznAXWKBGsFXEvS3YwQAAAAAAAAAAAEAAAAAAAAAAAAAAAEBAAAAAAAAAAEAAAAAAgAAAAAAAAABAAAAAQAAAAAAAAAA/gAAAF7pdgAAAAAA3L+7AOEAAAACAAAAAAUAAAAAAAAA2LXsKHE0OzrNuC43W4iqrbCXATbN7Vrv9g+pnVcIn3GagArX94/JpPmD7ur401jR2XnwnZmoLvY1Xxo0WD74LBx7bdSOFGlG0vFeOWlbeYxA4q2lJbWsyrKuTPOMLpEwH3ZE+P+4/OXT7izmt5JW/GV2Nl7A196dsQsvRIQ8GLFF2Y5ubgOInPSWRDS66JK044ocJTqSmdXV9cRvWd/ZndfGbgkDIldJ8is39yjTbms5WYbT+MMdTouDkXe7/RR/rPIyHYydU3V2iv833ptT/mMd1BjIn8kA4QAAAAIBAAAABQAAAAAAAABh32GLtt6GsmEcslmuPcrZItD+Juoo7ZWirMi8e1/FiijGNqRtdbCKZuhfQ1YpdnEbzWemjpg9Ri+xBWie/2Ahprm+AQ0MhNfjA0aCrBQUVGyF+m56UZSKjUMLDzti8lDk9Ab1gm5gPdjSqBvuU4GQOBPz/zBrbW5wj3RtP8YTSBz+zSbP16GLG7p9hgFqyHsCUW+6ufVBBxnm1av5XVBzEURqH8qICtpKY/KVf2r6aHq+JWRk2esXh2YYf5qGyV4A9nb2WQuF1uOr8SwtbqBFuqkt8X1UNwHhAAAAAgAAAAAFAAAAAAAAAIVsPPb8HMJiO1+TjmnkOIeYN9EoVXgiUe7Bq9RiQ4ztHgstL+cb7sREXnpfHrS2BkqNgQ/+BEnU8fOiOUNotBcKuYzeWSWfau7x/1Tz9cNY1gPCSCN1c0NbnJ9inLbIfZ7RLbPA5yISIH8oOgvEdpnqGxriTy8toW0ywIPBl4dUazTytK98Pdkr8H9/CmeaglIs1odZNQRiTjDUPLA1oamqtWk2WbC26OFqa2IjiF3PfZ0SbolXRKvjxI5GfjySiyM9kZgWTqVYYXFrfCOEnJn0wfCS1ZpSAQAAAABY5gICAAAAAHXdIAMAAAAAMW6VA+EAAAACAAAAAAUAAAAAAAAAvfPqvYsZRMMYI1k2OhwACh38eKO0TKhrivbr8PiNFQlMtcG4IUN6BIbEXi2uMbGLz52mQuEcrDqNNC97gX/hH7bsOzX2zc7/W9RN84QXI5Chj/ux12FfojelWw0A6mQC1D9uI9OvnMqus0jzwfUr22XZ1lsEkaJa09Ultt+cq5SWxe+zT2a8RQRqhZVjIccLMRj2A4JWF/Fm6hAnpIZueRM+w8kqlT8jPOg4yhfS83epSpsZ10InlFvdI0TlMlfCC3JwEYz7Kmu97PgK4gNB/KxJbLHAAkYFAAAAAJfwjwbhAAAAAgEAAAAFAAAAAAAAANSgL843Mnf0RxmaxGk53gkQ7xpAM8V7P/t47uXtXGn9cM/sp4tOiGesp9srdTnWt/GR3P/3vDVAkHN8oQMrFljMltsgaiyi4hTqwzCC+9LoLjaep07w1XRi0vxiu6GERZpymO5AZVj+IpjqYARHSzBcN+94SnZeRCIpbCairwiuzYwhjwTSIDwivA+aSTH16BbYFeTnMPro3ckmy1DMFWyDMpm0VhlQwOz3LPgq6tS3o21fwhwH91EoMPEQ00WlxD3/iLt7HwmUGc5tPuDLghfoL91cGQ9NCAAAAAAQHWMLAAAAAHzB3wvhAAAAAgEAAAAFAAAAAAAAAPmuZ1FO0XRHhWhzKoG4oJSG+/w02EWJtSbmrCSMue95NDHttEgAuRE1pyZL7PyBxLnH344VGI5l56TAwG5TfQSmLxOwUaerPylSAxeESNN8kjhO8Kg94Pf1q3axJ2rfcrnY6zmRRQTofcjbR0GU6hrZkFpzLoFiEq06HHen7rQEhfjXhGJMyM6PRjTSqt9feMTzmQYTr8vt/WbKxG12KmMCS99zpzoBpK03tAQEji1LppKrLxe7gZ3Fa0y8LtAV9TbRJR6i3tXoQ37FbBMFYy3tjPiFFTYBDOEAAAACAQAAAAUAAAAAAAAAstLV/6WV7dA5XYTvAhRQOntDqZZ84drf/s9rnNSbovBkKN5ji2MfaYf73FcQdU0jFmrGiyFLjLHb46pg5GqxXIbihmYCFSApmnl0N/YWCHdvRJnfcla+cMKT7kXPaVpJOgzVwG1dhGF23IgAvr5L48EoQT287dFkjYVEbUjZqXX/libCjJVd1axR9ff/ZxZ5jRCriBNSvi839hcWRN6Rsn0RJ1+e6BwkYzWqw/ooFS6BBGrDswfEaBW5Bsk9kKlo/nPE+A9Xsf9oG6Pah4BUDzJ1XRQlWZgNAAAAAOHymg3hAAAAAgEAAAAFAAAAAAAAABmpxN71jvpxOCn9tLD3XJl/ML/4FolPsSNaAmUcZHoHenLZLCMXOGvJDBc0q9ZSLAQ8Nfx0c/qE7uJZiGsqKASYSqKdgeXFo2wepE1stDzcCAxDJyjLJnC9liu/v3n0QJGOeIQBCzGwcnyDp7QNd1rvwnCgJhIvMhNS6Ryga2Loso0VMKktXJFju8Vjtg+84/eK0uSkd7BNrhBGUhVamGN+oxKlqCq9a7DajzxRgTIg1JczdTE/9tld1u4xajeiS8WI8l8UZWQgLpihUyPTxhHfG4PHjDLYEOEAAAACAAAAAAUAAAAAAAAAM/C8qWLHrEBC64V6eifmQTYo06XMWqGeZqouDXodAncw8BZ1l9slCrfq1GCl3lE0DXNwV8zR5swJSXbwZ0J8cQT3B9lzY2TsEdo6KWZx5pxQ1TUIkzJffsrTqfYzXgBBRP9kCJm6038TG++NYWmfXEabCXMpYAnwDm1VS47wmoJMeq6y308JW/AQHHU6Bk70YgUH6GnIqjAOhhJ3ybK+1IFC8/oJ+sglU1kwq0OSDrJ0NAyTwofUlA1N7zI4YgRCP/QaUY3HItn4wTpFFuY0s2zh2U0n/LERAAAAADGNZxLhAAAAAgAAAAAFAAAAAAAAAIwnIslomTMYwsUac0J/bW8AMV9Xj6UB9aZv4RTH64eAzntsUYrMAlO3P/zPaN2cfLT8pQtXjsCQUWZOu5VEFWtWqXRW55M2UuwosezUb4L3yWsHPHzkuisVSHFPOGg5CxfVhjot1F4VBK2GztqCU+WuyXSJjXUmr0SyTFeK+lBr1fEKlfzUnvDk3p7vx2B7kghgOpgalYXeGlrz+sH7djAqLEm8SFuYIXag11z9I13INs76f9el8uodJ/BYXPD0hwWo2VpRE1eaZff2TnirQ6Wn5/eqU4aREwAAAABifeUT4QAAAAIBAAAABQAAAAAAAAD4iy3IA0hgJX4UmK8fncwYa2w2qx9KvZqH0MFveNx/26bWjHQHROjFUnKFCyC+h0XItpep3RHOZcb1Wb+wTgYeLLDXJ053ayTcireYsWfskPDmtPG1G4TLHMbU9AjzSkvJ6EazHJ6QYp843mwxxKce/nzXRxCKmsydtVt6SmGGr/xCN/AGmizfb2AlyGhQCG25EyZ01e9cRJSbEXGdAVmV2Z2fojl2CcNRG4XkoNPVZUPOcvE6JD/PqdhKq/FPmeOlW+x74/qVjE6OfF4+ONp2m6PM7RawfRQAAAAAFKfRFAAAAADf5BYV4QAAAAIBAAAABQAAAAAAAAD1Pf/zLcdPklgjFnLA3pxkhBF9FKmHMNwyafqJiISQrubt7TxbiMARHmU2kFz0VvJHXLEMPAbLs06+kvd2/qkXAk+UjryAkXVbCengNIPg1+azSGIFmrcg+8ftK/mw2So0DGD7uRRK0RAJGOaCo6Sto0cv+gAGWIZbtciM7qpRV+Kz5cJfeInyD7WtxJBbT6xru2xaZdHgzumnQh0sp7U+xojlFyfJKbp5YWWRZSzWHJ2U5wbxEvnNYuqBIjpDzTJxxlu9dg77puvdXcUu5qpPKax/hRYKQRXhAAAAAgEAAAAFAAAAAAAAAHe3/rnYdJ0N2PniBgchLQYoLNL9R0ZdiueAeJ5k0nauSicNr+mTrrmURtXXoapecNAHlLO4Pju2UqCHwR4byGC264ndWBlEE8d++yROuj9z7RdX+Bv0QzQaUKIFezy3FbYrzYGAF+rN2oPED0VrI6qrCSmb9CUy35oSn6Zdx1a6aGso+98uoYw5GnJpOQkdmwJT/g82v8Snchae0cY5jGrB7EnQ+bHUck/yjc9Jdog1ql3p+i37vAMrsaS2B6KvNY7/XvwUcWboEXIwk/Yi8dIoZWU+INFyFeEAAAACAQAAAAUAAAAAAAAA1e3zDgrFYtoN2dLQWj9Adq+Pv/VQ3TD0ILNy3o8EHp4UxsWiSFfKvnQIkIqFN4UV14rS42WLp4SjTC31SnPuVF6NJ4gYuJRWPGEEaHgZK6OX1OtT22c8+3JREuzSIaUH8MJiHijtzNJWREc3VcWjtLtLJ6AaoLSfJNYuD0sW6n0ruj9eAIscALGlsylIaqzrbgdzjYYN3JRtY6EZUbaYTk3ka8uZh1l6PW6xLcGnUHOJNZqVRdaOLR0pDLNUjrmZgZb2o31IZO14XMRAELcc2sZIhqqTYB0W4QAAAAIBAAAABQAAAAAAAAB+O5dwt8NIjN329AhkmlHNeeJaK7fTE0mqnnNB38YLwfLRI2tWurd9eW+8pSvrlIOLyKC9MdKP1eqmWD+FFDpDjEn1Wo3n1w7fVWDipPKxDlh+8BdfrANeugUMyFvpLV+K/E+ScM0xsyYkahkNTjhNy3GWzEVLGnC9tGRdc+E/GE0O7gAnELoZc655vlNLRPZO8X86OxZw47iJrriSA0LJBAabSaHDHv8tXPbd8uV5hHfx6CczaUAnLA=="
      ],
      "leaves": [
        {
          "position": 12304348,
          "bytes": "AgAAAAAFAAAAAAAAANi17ChxNDs6zbguN1uIqq2wlwE2ze1a7/YPqZ1XCJ9xmoAK1/ePyaT5g+7q+NNY0dl58J2ZqC72NV8aNFg++Cwce23UjhRpRtLxXjlpW3mMQOKtpSW1rMqyrkzzjC6RMB92RPj/uPzl0+4s5reSVvxldjZewNfenbELL0SEPBixRdmObm4DiJz0lkQ0uuiStOOKHCU6kpnV1fXEb1nf2Z3Xxm4JAyJXSfIrN/co025rOVmG0/jDHU6Lg5F3u/0Uf6zyMh2MnVN1dor/N96bU/5jHdQY",
          "path": {
            "index": 12304348,
            "siblings": [
              "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
              "/kPWavpKmlxPnJ2on0/7UmNcjzQuf/tzHWjjbFmCByo="
            ]
          }
        }
      ],
      "clearedPositions": [
        7792990
      ],
      "transaction": "4yzkL1VB7QeVpXxL1JKTA9w94mm33uUNe9VKEo47WmF5KgLRKG5XhrW5q8ZeEZ6h81VcPeacwXbQiM7vLc6ZgFRp"
    }
  ],
  "nextCursor": "5",
  "hasMore": true,
  "asOf": "2026-11-17T07:29:42.728Z"
}

Types#

LedgerLeavesRequest#

Field Type Meaning
positions integer[] Tree positions to read, at most 256, each 0 to 4,294,967,295. A position sent twice is answered once.
root Hash (optional) The root to read at: one of the latest four verified roots, or a root the chain has committed since. Omit it for the latest verified root.

LedgerLeaves#

Field Type Meaning
root Hash The root every returned path leads to: the requested one, or the latest verified.
crossing U64 The Crossing whose Commit stored root, as LedgerRoot.k holds it while root is current; 0 before the first Commit.
slot U64 The slot of that Commit, as LedgerRoot.last_commit_slot holds it while root is current.
leaves Leaf[] The leaf at each requested position that holds one at root, with its Merkle path.
missing integer[] The requested positions that hold no leaf at root.
assets Asset[] One entry for each asset the returned balance leaves name, matched by registryIndex; empty when no balance leaf returns.

LedgerDiffs#

Field Type Meaning
items LedgerDiff[] The diffs after cursor, within fromCrossing and toCrossing and among crossings when sent, oldest first: up to limit, ending before 2 MiB, or one larger diff alone.
nextCursor U64 The cursor to send next: the last diff's, or the one sent when nothing follows.
hasMore boolean Whether more diffs follow within the requested span and list.
asOf Timestamp When the server read the diffs.

LedgerDiff#

A diff writes two kinds of leaf: 225-byte balance leaves, whose first byte is 2, and 197-byte encrypted account records, whose first byte is 1. A record holds an account’s private index, keys and nonce watermark, and nothing of its orders, Exits or history: the history is in the diff’s encrypted entries, and open orders and scheduled Exit pieces are in no diff (What stays off the diff). The byte layouts of the diff and of both leaves are fixed in the SDK’s WIRE.md (Diff).

Field Type Meaning
cursor U64 The diff's position in the public scan: its Crossing's index.
crossing U64 The Crossing whose Commit the diff belongs to.
previousRoot Hash The Ledger root before the Crossing.
root Hash The Ledger root after it, as the Commit stored it.
slot U64 The Commit's slot.
bytes Base64 The whole diff as logged on chain, base64: header, writes, proofs, entries and the Crossing's notional totals.
chunks Base64[] The diff in the log_diff chunks it was posted in, in order. Joined, they equal bytes.
leaves Leaf[] Every leaf the diff writes, balance leaves and account records, each with its Merkle path to root.
clearedPositions number[] Tree positions the Crossing emptied.
transaction Signature The Commit transaction's signature.

Leaf#

Field Type Meaning
position number The leaf's position in the tree.
bytes Base64 The leaf, base64: a 225-byte balance leaf, or a 197-byte encrypted account record.
path MerklePath Its Merkle path to the root it was served with.

MerklePath#

A leaf hashes as SHA-256 of 0x00 and the leaf, an interior node as SHA-256 of 0x01, the left child and the right child.

Field Type Meaning
index number The leaf's position; bit i chooses the branch at level i, from the leaf up.
siblings Hash[] The 32 sibling hashes, from the leaf up, base64.