Skip to main content
The DNSSEC proof model requires runtime spec 126 or newer and a matching OpenDispatch release. It is available on the alpha network, which currently runs spec 128 / transaction version 6. Domain Personas require a DNSSEC-signed TXT record and a valid delegation chain to an accepted DNS root trust anchor. Unsigned DNS and Directory attestations cannot complete this flow.
A Persona is a public name for a collective or policy operator. It can own delivery constraints and one delivery policy independently of a recipient DID. OpenPayload does not track Persona membership. A sender selects a Persona in the recipient address because it wants that Persona’s policy applied. A Persona is not an alias. Use it in the optional suffix of a delivery target, such as did:openpayload:...@example.com. Personas accept domain names and single-label names such as compliance. Single-label names do not claim a domain and need no DNS challenge. The DNS flow below is for a domain Persona.

DNSSEC requirements

Enable DNSSEC signing at your DNS provider and publish its DS record with the parent registrar. A signed zone without its parent delegation cannot register a Persona. The Directory collects the signed TXT record, zone keys, and delegation evidence; the chain verifies these offline against its configured DNS root trust anchors. This release supports DNSSEC algorithms 8, 10, 13, and 14 (RSA with SHA-256/SHA-512 and ECDSA P-256/P-384). Ed25519 DNSSEC (algorithm 15), CNAME challenges, and wildcard challenges are unsupported. Publish an exact TXT record at the returned name. The canonical domain can be at most 232 characters so the challenge name fits DNS limits. Delegated DS records must use SHA-256 or SHA-384, and TXT signatures must be no more than 48 hours old. DID signing keys remain Ed25519 and are separate from DNSSEC zone keys. Challenges last 48 hours; verification can last up to 365 days. The registration CLI defaults to 365 days; an API client supplies verification_days or verification_expires_at. DNSSEC evidence can expire sooner with its DNS signatures, so publish and verify within both limits. Renewals, domain transfers, and domain recovery also require fresh DNSSEC evidence. Existing confirmed Personas retain their recorded lease, but cannot renew through unsigned DNS. Pending challenges from the former Directory-attestor flow must be replaced.

Single-label names

For a single-label name, prepare a DID-signed registration, sign the returned canonical_payload with an operator DID controller key, and submit it. Use action register_named_persona, the operator DID, controller keys, threshold 1, the current operator nonce, and a future valid_until. No DNS step is involved. The new Directory preparation route reads the current operator nonce when you omit it and returns it with the payload. You can also read GET /persona-operators/{did}/nonce before a first registration. The existing Persona nonce route returns 404 for an unregistered name. Persona policies can define routing, archive forks, or other explicit actions. A policy does not itself prove that a recipient belongs to the collective; the Persona operator handles membership outside OpenPayload.

Domain-shaped names

The canonical DNS name is globally unique in chain state. A new registration is rejected when that Persona already exists; an existing Persona must use the renewal or authenticated transfer flow instead.

Before you begin

You need:
  • A canonical DNS name you control.
  • An active operator DID.
  • An authorized private signing key for that DID.
  • Permission to publish a TXT record below the domain.
The Directory normalizes an internationalized domain to its lowercase ASCII IDNA form and removes a trailing dot. A Persona must be a fully qualified name with at least two DNS labels. URLs, paths, ports, wildcard names, IP addresses, and names with a numeric-only top-level label are not Personas.

1. Request a DNS challenge

The response supplies the exact TXT record name and value. A challenge is valid for 48 hours, single-use, and bound to the Persona, operator DID, network, and nonce.

2. Publish the TXT record

Publish the returned value exactly:
DNS propagation time depends on your DNS provider and the record’s time to live.

3. Verify DNS and prepare the payload

Send the complete unsigned registration intent to the verification endpoint. Use the operator_nonce returned with the challenge.
Post that body to:
The Directory checks the TXT record and returns its DNSSEC evidence plus the exact canonical_payload for this intent.

4. Sign and submit

Decode canonical_payload and sign those exact bytes locally with signer_key_id. Submit the full intent again, including the DNSSEC evidence returned by verification, followed by the canonical payload and your signature:
Send this body to PUT /personas/example.com. 202 Accepted means the request was submitted to the chain. Read the Persona until its revision and verification timestamps reflect finalized state.

Renewal and controller changes

Renew DNS verification before verification_expires_at. Choose an explicit future expiration when verifying the intent; it can be at most 365 days away:
  • Create a challenge with action renew_persona.
  • Publish and verify the new TXT value.
  • Sign the returned canonical payload and submit it through PUT /personas/{persona}.
The existing operator can also use this renewal flow to reactivate an expired or revoked Persona. Policy, controller-rotation, constraint, and transfer mutations require the Persona to be active. Renewal restores an expired Persona when its current signing key is available. For a lost key or a domain held by a previous operator, use Persona recovery. Use PUT /personas/{persona}/controllers to change controller keys. Persona v1 requires a threshold of 1; the controller set may contain one through eight operator-DID signing keys, but each update uses one active-controller signature. The signing key must remain in the new set, so key removal is staged: add a replacement, wait for finalization, then use that replacement to authorize removal of the old key.

Transfer to a new operator

An operator transfer requires fresh DNS control plus authorization from both parties:
  1. Create a challenge with POST /personas/{persona}/transfer/dns-challenges and publish its TXT value.
  2. Verify the complete transfer intent with POST /personas/{persona}/transfer/dns-challenges/{challenge_id}/verify.
  3. Have the new operator sign the returned acceptance_payload, then send that signature to the matching /prepare endpoint.
  4. Have a current Persona controller sign the returned canonical_payload, then submit both signatures with PUT /personas/{persona}/operator.
The new controller set must contain one through eight signing keys published by the new operator DID, and new_controller_threshold must equal 1. The DNS verification can remain valid for at most 365 days. Transfer clears the old Persona policy so the previous operator cannot leave routing instructions behind. Publish a new policy after finalization if required. Transfer also replaces Persona-specific delivery constraints; omit delivery_constraints only when the Persona should fall through to DID and network constraints. Use DELETE /personas/{persona} with action revoke_persona to deactivate it. A revoked or expired Persona cannot win policy resolution. DNS proof establishes control of the domain at verification time. It does not establish the identity, reputation, or trustworthiness of the organization operating it.

Straight to the point