Skip to main content
This interface is deployed in the 6 September 2026 native-claim release. Use the matching verified addresses. Older deployments do not gain these methods automatically. SDK publication and hosted-service cutovers are tracked separately on that page.
Usernames such as alice.acme belong to the namespace Registrar. Universal Lookup remains the shared read entry point. A username claim does not call the top-level namespace Allocator and does not enter its objection or refund process. Network execution and storage fees apply separately from any username fee, including when the username fee is zero. The Owner 0.7.0 and Holder 0.5.0 SDKs default maxNativeFeeStroops to 50_000_000n (5 XLM) for native operations and reject a higher estimate before signing. Initial storage rent can exceed that limit. An application must review the estimate and explicitly choose any higher limit; the limit does not change the on-chain username price. The Owner and Holder SDK walkthrough shows application integration. The native claim storage reference defines every new stored value and canonical request type.

​
Capability and bindings

native_contracts checks the required namespace record, Registry-deployed attestations, clean provenance, selected Resolver pointer and current Wasm hashes against the Registry’s immutable templates. It does not call the Registrar or Resolver. This permits its use while either contract is already executing. A namespace owner’s ownership epoch changes on every completed ownership transition. Returning the namespace to a former owner does not restore old claim settings. Epoch numbers increase but are not necessarily consecutive for one namespace. An unsupported version or failed read never means Open registration. Installing a new SDK does not add native claims to an existing contract. Verify code and provenance as well as version answers before relying on the interface.

​
Owner controls

Unless shown otherwise, these methods return Result<result, Error>. Administrative writes require the current Registry owner. Console roles are not substitutes for that authorization. Initial configuration is absent: legacy manual owner issuance remains available, while public claiming is unavailable. Configuration chooses Manual or Public mode, enablement, admission, exact fee, G treasury and usage limits. It records the current ownership epoch and advances both policy and approval-grant epochs. Enabling stale-owner settings is rejected; a new owner must explicitly configure them. Pause and re-enable each advance the policy and grant epochs. Reservation changes advance the policy version. Public mode blocks the legacy issue and issue_batch routes even while paused. A public label must use public rules. The explicit reserved path is the administrative exception to public username prices and quotas. It still rejects an active name and records separate reserved-issuance usage. Reservation batches are atomic, contain 1–23 distinct canonical labels and reject active names when reserving them. Releasing a reservation leaves any holder unchanged. An issued reserved name stays reserved until its owner releases the reservation, including after the name expires. issue_reserved uses owner authorization and the holder’s default address. The atomic custom-destination variant requires both owner and holder authorization. Its first SDK release exposes simple assignment; a separate co-signing integration is needed to call the raw atomic reserved method for different owner/holder accounts.

​
Claim and recovery

A quote reports availability, reservation, current configuration, ownership epoch, record generation/expiry and lifetime usage. It does not reserve the label. available: true alone does not mean claiming is enabled or that the wallet is eligible. Inspect all relevant fields and the current policy. The first public claim flow uses a G claimant as holder and fee payer. The receiving destination can independently be G without a memo, G with ID/Text/Hash memo, M with its muxed ID, or C without a memo. The transaction records future receiving instructions; it does not make a payment to that destination. A fresh claim checks the complete signed context, current policy and owner epochs, fixed namespace term, exact fee, expected name generation/expiry, availability, reservation, wallet limit and admission rule. It then issues the name, transfers any fee directly to the treasury, initializes the destination and writes usage and a receipt in one transaction. Any failure rolls back those business effects. Network fees are separate. A matching existing receipt returns Replayed before fresh deadline, policy and authorization checks. It does not charge, increment usage, issue another name or rewrite a later destination. Reusing a request ID with a different operation or intent returns RequestIdConflict. Keep request IDs stable only for the same immutable intent. Credential nonce/signature renewal does not change that intent. History is not current ownership. After recovering a receipt, verify the current holder and generation through Lookup before associating a name with an app account. A missing receipt or interrupted RPC read does not prove that a transaction failed. Reconcile the original transaction before replacing it.

​
Exact authorization

For claim, claimant and optional approver each authorize the single argument [intent] with native Soroban authorization. The Merkle proof is not part of the signed intent; it can only demonstrate membership in the already committed root. The claimant’s authorization has these children, in order:
  1. Native asset contract transfer(claimant, fee_recipient, fee_amount) when the fee is nonzero.
  2. Resolver initialize_destination(label, claimant, fresh_generation, destination).
The optional G approver’s claim authorization has no children. The approver does not authorize a fee transfer or substitute for claimant authorization. Native account signer/threshold rules apply. The backend signs an authorization entry, while the claimant independently signs the transaction. An intent binds network, Registry, Registrar, namespace, request ID, execution window, label, claimant, complete destination, Resolver, existing generation/expiry, term, policy/owner/grant epochs and exact fee token/amount/recipient. See the type definitions. The business execution window is inclusive: valid_after <= now <= deadline. Its positive span must be at most 3600 seconds. Approval mode may configure a shorter maximum. Native credential expiration is a separate ledger-based limit; an expired or rotated credential is not proof that a previous request never completed.

​
Admission rules

Open admission accepts an empty proof and no approver. Allowlist admission verifies at most 32 sibling hashes against the configured root. Approval admission requires the configured separate G approver and an empty proof. The leaf is SHA-256 of this Soroban XDR tuple:
For each sibling, order the two 32-byte hashes lexicographically and compute SHA256(0x01 || smaller || larger). Use the final value as the root. This username allowlist is separate from the Allocator’s top-level namespace reservation proof. Wallet limits count cumulative public claims, including expiry/reissue claims. wallet_limit = 0 means unlimited. They do not count current holdings or prove one person. Reserved assignments have their own count. Approval requires a nonzero cumulative allowance, rate limit, window and lifetime. The owner chooses these numbers. The window is at most 31536000 seconds; approval lifetime is at most 3600 seconds. Counts survive mode, key, policy and owner changes. An active window cannot be reset or shortened by reconfiguration; a longer window may extend its end. The next approved claim starts a new window after expiry. The lifetime allowance is an absolute ceiling; only an explicit owner increase provides more headroom.

​
Transfer and renewal

Transfer acceptance requires the intended recipient. It checks the exact current holder, generation, name expiry and pending proposal expiry. It preserves the name’s expiry, advances the generation and initializes the selected destination atomically. A failed destination write leaves the existing holder and proposal unchanged. Claim pause, app admission and claim quotas do not gate this operation. Holder renewal uses the immutable positive default term. It checks the recorded holder, generation and expiry, then extends from max(now, old_expiry). It preserves the generation and existing records. It is available within the shorter of 30 days or one policy term before expiry, subject to the resulting expiry being no more than 100 years from execution and within the signed result bounds. Zero-expiry or permanent names cannot use it. The legacy owner renewal method also rejects zero extension and leases beyond the same 100-year bound. An expired holder may renew only before reissue wins. There is no guaranteed grace period. preview_destination returns the exact-generation receiving instructions, including when inactive. It rejects mismatched generations and invalid configured payment records. Ordinary payment resolution still rejects expired names. Preview is not a new payment destination or a bypass of live resolution. The initializer is restricted to the bound native Registrar and exact holder consent. It accepts only a destination for a generation freshly created by claim, reserved assignment or accepted transfer. It derives the node from its bound namespace, checks native bindings, rejects already initialized/same-or-newer data, and makes no callback into the active Registrar. It is not a general owner record setter, and renewal does not call it.

​
Errors and compatibility

Existing Registrar error codes 1–20 retain their values. New codes are: Registry additionally reports OwnershipEpochUnavailable (29) and OwnershipEpochOverflow (30). Resolver adds InitializationContextMismatch (22), DestinationAlreadyInitialized (23) and GenerationMismatch (24). An atomic Registrar call maps a failed initializer to Registrar error 41 and aborts the whole operation. A contract rejection does not authorize changing the destination, dropping a memo, opening admission or charging different terms on a retry. Namespace template changes require a successor deployment; this reference does not migrate existing Registry records or make old contracts permanent.