Section 04
Reference
Generated JSON schemas, protocol constants, and activation formulas. Machine-readable artifacts for validation and integration.
JSON Schemas
Generated from Go source via go run ./cmd/schemas. These schemas define the canonical wire format for all Urma data structures.
claim.json
UrmaClaim JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://go.lumeweb.com/urma/urma-claim",
"properties": {
"version": {
"type": "integer",
"description": "Protocol version",
"examples": [
0
]
},
"location": {
"type": "string",
"enum": [
"sia"
],
"description": "Storage backend identifier"
},
"sourceClaimId": {
"items": {
"type": "integer"
},
"type": "string",
"pattern": "[0-9a-f]{40}",
"maxItems": 20,
"minItems": 20,
"format": "hex",
"description": "Hex-encoded 20-byte ClaimID of the LBRY source claim"
},
"dataKey": {
"items": {
"type": "integer",
"format": "byte"
},
"type": "array",
"maxItems": 32,
"minItems": 32,
"description": "AES-256 encryption key for file content"
},
"locationData": {
"description": "Location-specific retrieval data. Structure depends on the location field"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"version",
"location",
"sourceClaimId",
"dataKey",
"locationData"
]
}manifest.json
ManifestPage (page 0) JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://go.lumeweb.com/urma/sia/manifest",
"properties": {
"streamName": {
"type": "string",
"description": "Original stream name"
},
"streamType": {
"type": "string",
"description": "LBRY stream type"
},
"suggestedFileName": {
"type": "string",
"description": "Suggested file name"
},
"blobs": {
"items": {
"properties": {
"blobHash": {
"type": "string",
"description": "SHA-384 hash of encrypted blob (hex)"
},
"iv": {
"type": "string",
"description": "AES IV for blob content (hex)"
},
"blobLength": {
"type": "integer",
"description": "LBRY blob size in bytes"
},
"blobNum": {
"type": "integer",
"description": "Position in stream (0-indexed)"
},
"slabKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32,
"description": "Sia slab encryption key"
},
"minShards": {
"type": "integer",
"description": "Minimum sectors for recovery"
},
"sectors": {
"items": {
"properties": {
"root": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
},
"hostKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
}
},
"additionalProperties": false,
"type": "object",
"required": [
"root",
"hostKey"
]
},
"type": "array",
"description": "Pinned sectors for this blob"
},
"slabOffset": {
"type": "integer",
"description": "Byte offset into slab data"
},
"slabLength": {
"type": "integer",
"description": "Number of data bytes in slab slice"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"blobHash",
"iv",
"blobLength",
"blobNum",
"slabKey",
"minShards",
"sectors",
"slabOffset",
"slabLength"
]
},
"type": "array",
"description": "Blob entries mapping LBRY blob hashes to Sia locations"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"streamName",
"streamType",
"suggestedFileName",
"blobs"
]
}manifest-blobs.json
ManifestBlobs (continuation) JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://go.lumeweb.com/urma/sia/manifest-blobs",
"properties": {
"blobs": {
"items": {
"properties": {
"blobHash": {
"type": "string",
"description": "SHA-384 hash of encrypted blob (hex)"
},
"iv": {
"type": "string",
"description": "AES IV for blob content (hex)"
},
"blobLength": {
"type": "integer",
"description": "LBRY blob size in bytes"
},
"blobNum": {
"type": "integer",
"description": "Position in stream (0-indexed)"
},
"slabKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32,
"description": "Sia slab encryption key"
},
"minShards": {
"type": "integer",
"description": "Minimum sectors for recovery"
},
"sectors": {
"items": {
"properties": {
"root": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
},
"hostKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
}
},
"additionalProperties": false,
"type": "object",
"required": [
"root",
"hostKey"
]
},
"type": "array",
"description": "Pinned sectors for this blob"
},
"slabOffset": {
"type": "integer",
"description": "Byte offset into slab data"
},
"slabLength": {
"type": "integer",
"description": "Number of data bytes in slab slice"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"blobHash",
"iv",
"blobLength",
"blobNum",
"slabKey",
"minShards",
"sectors",
"slabOffset",
"slabLength"
]
},
"type": "array",
"description": "Blob entries for this continuation page"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"blobs"
]
}manifest-blob.json
ManifestBlob entry JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://go.lumeweb.com/urma/sia/manifest-blob",
"properties": {
"blobHash": {
"type": "string",
"description": "SHA-384 hash of encrypted blob (hex)"
},
"iv": {
"type": "string",
"description": "AES IV for blob content (hex)"
},
"blobLength": {
"type": "integer",
"description": "LBRY blob size in bytes"
},
"blobNum": {
"type": "integer",
"description": "Position in stream (0-indexed)"
},
"slabKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32,
"description": "Sia slab encryption key"
},
"minShards": {
"type": "integer",
"description": "Minimum sectors for recovery"
},
"sectors": {
"items": {
"properties": {
"root": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
},
"hostKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
}
},
"additionalProperties": false,
"type": "object",
"required": [
"root",
"hostKey"
]
},
"type": "array",
"description": "Pinned sectors for this blob"
},
"slabOffset": {
"type": "integer",
"description": "Byte offset into slab data"
},
"slabLength": {
"type": "integer",
"description": "Number of data bytes in slab slice"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"blobHash",
"iv",
"blobLength",
"blobNum",
"slabKey",
"minShards",
"sectors",
"slabOffset",
"slabLength"
]
}sia.json
Sia backend (SlabSlice + sectors) JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"claim": {
"properties": {
"version": {
"type": "integer",
"description": "Protocol version",
"examples": [
0
]
},
"location": {
"type": "string",
"enum": [
"sia"
],
"description": "Storage backend identifier"
},
"sourceClaimId": {
"items": {
"type": "integer"
},
"type": "string",
"pattern": "[0-9a-f]{40}",
"maxItems": 20,
"minItems": 20,
"format": "hex",
"description": "Hex-encoded 20-byte ClaimID of the LBRY source claim"
},
"dataKey": {
"items": {
"type": "integer",
"format": "byte"
},
"type": "array",
"maxItems": 32,
"minItems": 32,
"description": "AES-256 encryption key for file content"
},
"locationData": {
"description": "Location-specific retrieval data. Structure depends on the location field"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"version",
"location",
"sourceClaimId",
"dataKey",
"locationData"
]
},
"manifest": {
"properties": {
"streamName": {
"type": "string",
"description": "Original stream name"
},
"streamType": {
"type": "string",
"description": "LBRY stream type"
},
"suggestedFileName": {
"type": "string",
"description": "Suggested file name"
},
"blobs": {
"items": {
"properties": {
"blobHash": {
"type": "string",
"description": "SHA-384 hash of encrypted blob (hex)"
},
"iv": {
"type": "string",
"description": "AES IV for blob content (hex)"
},
"blobLength": {
"type": "integer",
"description": "LBRY blob size in bytes"
},
"blobNum": {
"type": "integer",
"description": "Position in stream (0-indexed)"
},
"slabKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32,
"description": "Sia slab encryption key"
},
"minShards": {
"type": "integer",
"description": "Minimum sectors for recovery"
},
"sectors": {
"items": {
"properties": {
"root": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
},
"hostKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
}
},
"additionalProperties": false,
"type": "object",
"required": [
"root",
"hostKey"
]
},
"type": "array",
"description": "Pinned sectors for this blob"
},
"slabOffset": {
"type": "integer",
"description": "Byte offset into slab data"
},
"slabLength": {
"type": "integer",
"description": "Number of data bytes in slab slice"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"blobHash",
"iv",
"blobLength",
"blobNum",
"slabKey",
"minShards",
"sectors",
"slabOffset",
"slabLength"
]
},
"type": "array",
"description": "Blob entries mapping LBRY blob hashes to Sia locations"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"streamName",
"streamType",
"suggestedFileName",
"blobs"
]
},
"manifestBlobs": {
"properties": {
"blobs": {
"items": {
"properties": {
"blobHash": {
"type": "string",
"description": "SHA-384 hash of encrypted blob (hex)"
},
"iv": {
"type": "string",
"description": "AES IV for blob content (hex)"
},
"blobLength": {
"type": "integer",
"description": "LBRY blob size in bytes"
},
"blobNum": {
"type": "integer",
"description": "Position in stream (0-indexed)"
},
"slabKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32,
"description": "Sia slab encryption key"
},
"minShards": {
"type": "integer",
"description": "Minimum sectors for recovery"
},
"sectors": {
"items": {
"properties": {
"root": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
},
"hostKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
}
},
"additionalProperties": false,
"type": "object",
"required": [
"root",
"hostKey"
]
},
"type": "array",
"description": "Pinned sectors for this blob"
},
"slabOffset": {
"type": "integer",
"description": "Byte offset into slab data"
},
"slabLength": {
"type": "integer",
"description": "Number of data bytes in slab slice"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"blobHash",
"iv",
"blobLength",
"blobNum",
"slabKey",
"minShards",
"sectors",
"slabOffset",
"slabLength"
]
},
"type": "array",
"description": "Blob entries for this continuation page"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"blobs"
]
},
"manifestBlob": {
"properties": {
"blobHash": {
"type": "string",
"description": "SHA-384 hash of encrypted blob (hex)"
},
"iv": {
"type": "string",
"description": "AES IV for blob content (hex)"
},
"blobLength": {
"type": "integer",
"description": "LBRY blob size in bytes"
},
"blobNum": {
"type": "integer",
"description": "Position in stream (0-indexed)"
},
"slabKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32,
"description": "Sia slab encryption key"
},
"minShards": {
"type": "integer",
"description": "Minimum sectors for recovery"
},
"sectors": {
"items": {
"properties": {
"root": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
},
"hostKey": {
"items": {
"type": "integer"
},
"type": "array",
"maxItems": 32,
"minItems": 32
}
},
"additionalProperties": false,
"type": "object",
"required": [
"root",
"hostKey"
]
},
"type": "array",
"description": "Pinned sectors for this blob"
},
"slabOffset": {
"type": "integer",
"description": "Byte offset into slab data"
},
"slabLength": {
"type": "integer",
"description": "Number of data bytes in slab slice"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"blobHash",
"iv",
"blobLength",
"blobNum",
"slabKey",
"minShards",
"sectors",
"slabOffset",
"slabLength"
]
}
},
"additionalProperties": false,
"type": "object",
"required": [
"claim",
"manifest",
"manifestBlobs",
"manifestBlob"
]
}RPC Reference
LBRY daemon RPCs used for claim discovery and resolution. All queries are local against the node's own claimtrie database.
| Field | Type | Description |
|---|---|---|
| getclaimsforname | RPC | Returns all claims at a name (primary discovery). |
| getclaimsfornamebyid | RPC | Returns a specific claim by ID. |
| getclaimsfornamebybid | RPC | Returns a claim by bid position. |
| getclaimsfornamebyseq | RPC | Returns a claim by index sequence. |
| getchangesinblock | RPC | Returns all names changed in a block. |
| normalize | RPC | Returns the normalized form of a claim name. |
Claim Status Lifecycle
Claims transition through three states. Only Activated claims are processed by the validation pipeline.
| Field | Type | Description |
|---|---|---|
| Activated | Status | Live, bid counts toward ranking. Process. |
| Accepted | Status | Waiting for activation delay. Skip. |
| Deactivated | Status | UTXO spent (abandoned). Skip. |
Activation Delay
For new claims at a name with an existing controlling claim:
formula
delay = min(4032, (currentHeight - lastTakeoverHeight) / 32)
// Maximum delay: 4032 blocks (~7 days)
// First claim at a fresh name: delay = 0 (immediate activation)Security Properties
Name squatting (global)
Multiple claims coexist; squatting doesn't remove others
Name squatting (creator)
Cryptographically impossible without channel key
Spoofed Urma data
Download-time SHA-384 verification per blob
Stale/expired Urmas
Storage fetch fails at filter step 5; client skips
Spam flood
Economic: each claim locks LBC in a UTXO
Censorship
Claimtrie replicated on every full node; local resolution
Takeover attack
Activation delay (up to ~7 days) slows displacement
Forged creator signature
ECDSA verification against channel public key