Native claim storage

Use this reference to decode native username claim state and construct the exact on-chain request types. Read it alongside the complete current contract storage reference, which covers the shared Registry, Allocator, Registrar, Resolver, Primary and Lookup storage. For application integration, start with the native claim interface or SDK walkthrough. The historical native-muxed schema applies only to its own deployment. This page distinguishes three kinds of data:

Stored keys: Registry ownership epochs and Registrar configuration, reservations, usage and receipts.
Request types: the complete intent authorized for a claim, reserved assignment, transfer or renewal.
Return values: quotes and destination previews, which are not additional stored records.

Match the code hashes and contract addresses in the current deployment. A version getter alone does not establish storage compatibility. Registry factory templates describe new deployments. Existing namespaces use their recorded native code pins; see governed storage.

Encoding conventions

The XDR conventions also apply here. A named struct is a map keyed by field-name symbols. Enum variants are symbol vectors with their exact payload arity, not integer ordinals. BytesN<32> is raw 32-byte SCV_BYTES; u64 and i128 must retain their full precision. Labels use canonical lowercase ASCII and are stored as Bytes. Contract field names use snake_case. The SDK exposes equivalent camelCase fields, bigint numbers and lowercase 64-character hex identifiers. Do not hash a JSON serialization when reproducing a contract commitment.

namespace_node = SHA256(zero32 || SHA256(namespace_label_bytes))
name_node      = SHA256(namespace_node || SHA256(username_label_bytes))

Registry additions

Key or field	Storage	Value and rule
`DataKey::OwnershipSequence`	Instance	Required `u64`, initialized to `0` in the constructor
`Record.owner_epoch`	In persistent `DataKey::Node(namespace_node)`	The next checked global ownership sequence value at each allocation, reserved award or accepted ownership transfer

The current namespace record is:

struct Record {
    owner: Address,
    owner_epoch: u64,
    resolver: Option<Address>,
    registrar_status: RegistrarStatus,
    resolver_status: ResolverStatus,
}

Other Registry keys and Config retain their documented shapes. The ownership sequence is Registry-wide, so a particular namespace’s epochs can skip numbers. An absent sequence is an error, not a reset to zero. Increment overflow also errors. The required namespace record carries its epoch through ordinary writes. A transfer back to a former owner receives a new epoch. owner_epoch(node) reads this field. template_hashes() returns Registrar then Resolver Wasm hashes for new deployments. In governed mode, native_contracts(node) verifies the existing namespace against its NativeV1(node) code pins and attestations. Approved upgrades update those pins atomically. This extra required field changes the Registry record schema. An old four-field record is not a native-claim record with an implied epoch. Use the old schema only for its matching deployment. Existing owner/resolver pointers and namespace transfer proposals keep their original meanings.

Registrar keys

The existing DataKey::Config, Name(node) and PendingTransfer(node) shapes remain unchanged. In particular, the name still stores holder, built-in address, expiry and ownership generation. Claim state uses a separate ClaimKey enum:

Instance policy and counters

Key	Storage	Value	Fresh absence
`ClaimKey::ConfigV1`	Instance	`ClaimConfig`	Unconfigured/manual; public claiming unavailable
`ClaimKey::PolicyVersionV1`	Instance	`u64`	`0`, before any configuration, reservation or grace change
`ClaimKey::GrantEpochV1`	Instance	`u64`	`0`, before any configuration or enable/pause change
`ClaimKey::ApprovalUsageV1`	Instance	`ApprovalUsage`	All fields `0`, before any approved claim
`ClaimKey::RenewalGraceV1`	Instance	`u64`	`0` seconds of renewal protection
`ClaimKey::RenewalGraceEffectiveFromV1`	Instance	`u64`	No activation cutoff; no expiry is protected

Persistent claim records

Key	Storage	Value	Fresh absence
`ClaimKey::ReservedV1(name_node)`	Persistent	`bool`	Never reserved; an explicit release stores `false`
`ClaimKey::UsageV1(holder)`	Persistent	`ClaimUsage`	Both fields `0`, before that holder’s first public/reserved issue
`ClaimKey::ReceiptV1(holder, request_id)`	Persistent	`ClaimReceipt`	No committed operation under this ID

For example, a receipt key encodes as:

SCV_VEC [Symbol("ReceiptV1"), Address(holder), Bytes(request_id)]

Instance keys are entries of the single contract-instance storage map, not separate persistent ledger entries. The suffix V1 belongs to the key name. It is not an integer schema-version record. No new application state uses temporary storage; native authorization nonce entries belong to the Soroban runtime separately.

Configuration and usage types

These types define ConfigV1, UsageV1 and ApprovalUsageV1.

enum ClaimMode {
    Manual,
    Public,
}

enum Admission {
    Open,
    Allowlist(BytesN<32>),
    Approval(Address),
}

struct ClaimSettings {
    mode: ClaimMode,
    enabled: bool,
    admission: Admission,
    fee_token: Address,
    fee_amount: i128,
    fee_recipient: Address,
    /// Zero is unlimited. Counts are lifetime public admissions, not holdings.
    wallet_limit: u64,
    /// Absolute lifetime approved-admission ceiling, not a resettable balance.
    approval_allowance: u64,
    approval_rate_limit: u64,
    approval_window_secs: u64,
    approval_ttl_secs: u64,
}

struct ClaimConfig {
    settings: ClaimSettings,
    owner_epoch: u64,
    policy_version: u64,
    grant_epoch: u64,
}

Usage records contain cumulative counts and the current approval window:

struct ClaimUsage {
    public_claims: u64,
    reserved_issues: u64,
}

struct ApprovalUsage {
    total: u64,
    window_used: u64,
    window_ends: u64,
}

fee_token must be the current network’s native XLM asset contract. fee_amount is nonnegative; 0 means free. fee_recipient must be G. Approval mode requires a G approver distinct from the namespace owner, fee recipient and claimant, plus nonzero explicit allowance, rate limit, window and lifetime. Outside Approval mode, all four approval-specific numeric settings are zero. wallet_limit = 0 means unlimited cumulative public claims. Configuration stamps the current owner epoch. Configure and enable/pause operations advance both policy and grant epochs. Reservations and renewal-grace changes advance the policy version, including when changed before public claiming is first configured. Grace is an additive policy, not a field appended to ClaimConfig or Name. RenewalGraceV1 accepts 0–7,776,000 seconds. Enabling stores the current ledger timestamp in RenewalGraceEffectiveFromV1; only expiries at or after that timestamp qualify. Positive duration changes retain the cutoff. Disabling removes it, and re-enabling starts a new activation. A legacy nonzero duration without the cutoff does not protect expired names. Grace prevents ordinary reissue while leaving the ownership expiry and resolution rules unchanged. An ownership transfer does not rewrite this stored configuration. Its enabled flag may remain true, but it is ineffective when ClaimConfig.owner_epoch differs from Registry’s current epoch. A new owner must configure explicitly. SDKs and interfaces must compare the epochs when displaying whether claiming is usable. public_claims counts lifetime ordinary claims, including expired-name reissues. reserved_issues counts privileged reserved assignments. Neither count decreases on transfer, expiry, reclaim, mode change or ownership change. The approval total and active window likewise survive policy and key changes. An allowance is an absolute lifetime ceiling, not a balance automatically replenished by rotation.

Request types

Payment destination

These types represent the complete receiving instructions included in an intent:

enum PaymentMemo {
    None,
    Id(u64),
    Text(String),
    Hash(BytesN<32>),
}

struct Payment {
    address: Address,
    memo: PaymentMemo,
}

struct MuxedPayment {
    account: Address,
    id: u64,
}

enum PaymentDestination {
    Direct(Payment),
    Muxed(MuxedPayment),
}

Direct supports G with None/ID/Text/Hash or C with None. Muxed requires a G base account and an exact u64 ID. It does not carry a transaction memo. The public SDK displays a canonical M string with memo: { type: "none" }.

Shared request context

Every intent includes the same network, contract, request-ID and execution-window context:

struct RequestContext {
    network: BytesN<32>,
    registry: Address,
    registrar: Address,
    namespace: BytesN<32>,
    request_id: BytesN<32>,
    valid_after: u64,
    deadline: u64,
}

Public claim

A public claim binds the label, claimant, destination, current policy and exact fee. Registrar contract_claim_version() == 1 adds G and C claimant support without changing this intent’s shape or the original claim_version() == 1. A C claimant authorizes through its contract wallet; the approver and fee recipient remain G identities under the current configuration rules.

struct ClaimIntent {
    context: RequestContext,
    label: Bytes,
    claimant: Address,
    destination: PaymentDestination,
    resolver: Address,
    expected_generation: Option<u64>,
    expected_expiry: Option<u64>,
    term_secs: u64,
    owner_epoch: u64,
    policy_version: u64,
    grant_epoch: u64,
    fee_token: Address,
    fee_amount: i128,
    fee_recipient: Address,
}

Reserved assignment

A reserved assignment binds its holder and destination without a username fee.

struct ReservedIntent {
    context: RequestContext,
    label: Bytes,
    holder: Address,
    destination: PaymentDestination,
    resolver: Address,
    expected_generation: Option<u64>,
    expected_expiry: Option<u64>,
    term_secs: u64,
    owner_epoch: u64,
    policy_version: u64,
}

Transfer acceptance

Transfer acceptance binds the current proposal and the recipient’s chosen destination.

struct TransferIntent {
    context: RequestContext,
    label: Bytes,
    from: Address,
    to: Address,
    expected_generation: u64,
    expected_expiry: u64,
    proposal_expires: u64,
    destination: PaymentDestination,
    resolver: Address,
}

Holder renewal

Renewal binds the current name record and the permitted range for its new expiry.

struct RenewIntent {
    context: RequestContext,
    label: Bytes,
    holder: Address,
    expected_generation: u64,
    expected_expiry: u64,
    term_secs: u64,
    min_new_expiry: u64,
    max_new_expiry: u64,
}

A fresh name uses expected_generation = None and expected_expiry = None. Reissue binds both previous values. First issuance creates generation 0; reissue, accepted transfer and reclaim advance it with checked arithmetic. Renewal preserves it. An active record is not available for ordinary issuance. term_secs must equal the namespace’s immutable default term. The public claim intent also binds all fee fields and current policy/owner/grant epochs. An atomic reserved assignment uses the current owner and policy epochs but has no username fee. Transfer and renewal do not depend on claim policy or approval epochs. Transfer binds the exact pending sender/recipient, original generation, name expiry and proposal deadline. Renewal binds the holder/generation/current expiry and permitted result range. For an expired name, the renewal result is based on actual execution time, so the signed range accommodates the reviewed timing window.

Quote and receipt types

Quote

A quote is a read result, not a reservation or additional stored key.

enum ClaimConfigState {
    Unconfigured,
    Configured(ClaimConfig),
}

struct ClaimQuote {
    network: BytesN<32>,
    registry: Address,
    registrar: Address,
    namespace: BytesN<32>,
    resolver: Address,
    label: Bytes,
    node: BytesN<32>,
    claimant: Address,
    config: ClaimConfigState,
    owner_epoch: u64,
    policy_version: u64,
    available: bool,
    reserved: bool,
    generation: Option<u64>,
    expires_at: Option<u64>,
    term_secs: u64,
    now: u64,
    usage: ClaimUsage,
    approval_usage: ApprovalUsage,
}

Receipt and result

ClaimReceipt is stored under ReceiptV1; ClaimResult wraps it in an operation response.

enum ClaimOperation {
    Claim,
    Reserved,
    Transfer,
    Renew,
}

struct ClaimReceipt {
    operation: ClaimOperation,
    intent_hash: BytesN<32>,
    node: BytesN<32>,
    holder: Address,
    generation: u64,
    expires_at: u64,
    fee_amount: i128,
    fee_token: Address,
    fee_recipient: Option<Address>,
    ledger: u32,
    timestamp: u64,
}

enum ClaimResult {
    Fresh(ClaimReceipt),
    Replayed(ClaimReceipt),
}

ClaimQuote.config is an explicit enum: [Symbol("Unconfigured")] or [Symbol("Configured"), ClaimConfig]. This differs from the standalone claim_config() getter’s Option<ClaimConfig>, whose absence is SCV_VOID. The SDK converts either absence representation to null at its respective API. Quote availability, reservation and enablement are separate facts. An expired record still supplies its prior generation/expiry, and applicable grace can keep it unavailable for reissue. A quote’s available flag is not proof that the requesting wallet satisfies admission or quota rules. Receipts are stored under the receiving holder’s identity for reserved assignment, transfer and renewal, and the claimant for a public claim. The key spans operation types: a holder cannot reuse the same request ID for a different operation. The commitment is:

intent_hash = SHA256(SorobanXDR((Symbol(exact_method_name), complete_intent)))

The exact method name is one of claim, issue_reserved_with_destination, accept_transfer_with_destination or renew_holder. Merkle proof bytes and native credential nonce/signatures are excluded. A different business deadline or epoch changes the commitment; refreshing only credentials does not. A matching receipt yields historical Replayed without writes or renewed business authorization. It never reinitializes records after transfer/reissue. An unmatched commitment is an error. Receipt expiry/generation are historical, not a replacement for current Lookup state. Free operations have fee_amount = 0 and fee_recipient = None; fee_token still identifies native XLM.

Resolver behavior

The Resolver exposes initialization_version() = 1, restricted initialize_destination and preview_destination. These methods use the existing payment-version-2 record encodings and add no storage keys. Initialization writes the existing generation-bound Addr(node), Text(node, Symbol("payment")) and PaymentConfigured(node, generation) records together. It refuses an existing marker for that generation or address/payment records from the same or a newer generation. Old-generation records can be replaced when the trusted Registrar creates a new ownership generation. The caller must be the bound, currently clean native Registrar, and the exact holder must consent. The Registrar creates the generation internally; callers cannot use this helper as an arbitrary generation or owner-setting API. The initializer does not call back into the active Registrar. It writes no reverse or Primary identity automatically.

Destination preview

Preview returns a read-only value, not another stored record:

struct DestinationPreview {
    node: BytesN<32>,
    holder: Address,
    generation: u64,
    expires_at: u64,
    active: bool,
    destination: PaymentDestination,
}

Preview requires an exact generation and valid configured payment state, but can return active = false for an expired name. Ordinary payment reads remain strict: expired names do not resolve. Renewal leaves the existing generation and records intact, so the holder should review this preview before reactivating them.

TTL, restoration and events

Ownership expiry and storage lifetime remain independent. An archived receipt, reservation, usage entry or name must restore or fail. An application must not replace an unavailable read with zero usage, an unreserved label or a fresh request. No admin action deletes usage or receipts to reset these values.

Maintaining stored entries

Registrar TTL extensions use a threshold of 2,500,000 ledgers and a target of 3,000,000 ledgers, clamped to the network maximum. Policy and configuration writes extend the instance lifetime. Receipt, usage and reservation writes extend their persistent entries. Name writes extend the name entry and instance. Keeping entries live costs network resources even when there is no username renewal fee. touch_claim_state(holder, request_ids, labels) is permissionless. It extends the instance, that holder’s existing usage and the supplied existing receipt and reservation entries. The combined supplied request/label count is at most 23; the return count excludes the instance. It skips keys that were never created. It does not enumerate every wallet, request or reservation. Keep a discovery list or use indexed events to select entries; verify values against the contracts.

Events

Event topics	Data
`(Symbol("claimcfg"))`	`ClaimConfig`
`(Symbol("grace"))`	`(secs: u64, policy_version: u64)`
`(Symbol("reserved"), name_node)`	`(label, reserved, policy_version)`
`(Symbol("claim_v1"), namespace_node, holder)`	`(request_id, ClaimReceipt)`

The existing issued, transfer, renewed and name_v1 lifecycle events remain. The renewed payload remains (label, name_node, new_expiry). Destination writes retain the native Resolver payment events. Replaying a receipt emits no new claim event because it performs no business mutation. Native username claims add no storage keys to Allocator, Primary or Lookup. Earlier deployments retain their own records and namespace escrow liabilities.

​Encoding conventions

​Registry additions

​Registrar keys

​Instance policy and counters

​Persistent claim records

​Configuration and usage types

​Request types

​Payment destination

​Shared request context

​Public claim

​Reserved assignment

​Transfer acceptance

​Holder renewal

​Quote and receipt types

​Quote

​Receipt and result

​Resolver behavior

​Destination preview

​TTL, restoration and events

​Maintaining stored entries

​Events