Registry & Resolver

The state of every did:stellar lives in the did-stellar-registry Soroban contract. The hosted resolver at `https://did.acta.build` is a stateless HTTP convenience on top of it: it resolves DIDs, prepares unsigned XDRs, and submits signed ones. It requires no authentication and never holds keys.

On-chain registry

• One entry per DID in Soroban persistent storage, keyed by the 16-byte DID id.
• Reads are free: resolution uses getLedgerEntries on Stellar RPC, no transaction or fee involved.
• The contract is a *dumb store*: it persists exactly what register/update send. It never fills defaults or invents keys. Bookkeeping fields (version, createdLedger, updatedLedger, deactivated) are contract-owned and overwrite anything the caller passes.

The DID record

DidKey is { publicKeyMultibase }. DidService is { idSuffix, serviceType, serviceEndpoint }, exposed in the document as {did}#service-{idSuffix}.

Record limits

Contract operations

Contract error codes are documented in Contract errors (did:stellar registry table).

Deployed contracts

These are the registries used by did.acta.build, the ACTA API, and the libraries' defaults.

Hosted resolver (did.acta.build)

• No authentication and no key custody: it only handles unsigned and signed XDRs.
• Multi-network: one deployment serves both testnet and mainnet, routing each request by the network inside the DID.
• Stateless and horizontally scalable; resolution results are cached ~30 seconds.

Endpoints

Resolution endpoint

GET /1.0/identifiers/{did}

Returns the W3C DID Resolution Result (didDocument + didDocumentMetadata + didResolutionMetadata). Content negotiation: application/did+ld+json (default, with @context) or application/did+json.

curl https://did.acta.build/1.0/identifiers/did:stellar:testnet:znfxngsh46vkyqu6inrx4omphi

GET /v1/dids/stellar/{did}

Returns the raw on-chain record without W3C wrapping: { did, didId, record: { controller, authentication, assertionMethod, keyAgreement, services, version, createdLedger, updatedLedger, deactivated } }. Use it to read the current version before an update, or the controller directly.

Mutation endpoints

All mutations are POST and follow the same prepare/submit pattern used across ACTA.

Register (prepare):

curl -X POST https://did.acta.build/v1/dids/stellar \
  -H "Content-Type: application/json" \
  -d '{
    "did": "did:stellar:testnet:...",
    "sourcePublicKey": "G...",
    "record": {
      "controller": "G...",
      "authentication": [{ "publicKeyMultibase": "z6Mk..." }],
      "assertionMethod": [{ "publicKeyMultibase": "z6Mk..." }],
      "keyAgreement": [],
      "services": []
    }
  }'

Response: { "xdr": "...", "network": "testnet", "networkPassphrase": "..." }

Submit (after signing with the controller wallet):

curl -X POST https://did.acta.build/v1/dids/stellar/submit \
  -H "Content-Type: application/json" \
  -d '{ "signedXdr": "AAAA..." }'

Response: { "txId": "..." }

• Update: POST /v1/dids/stellar/{did}/update with { expectedVersion, sourcePublicKey, record }. Full record replacement; a stale version returns 409 version_mismatch.
• Transfer: POST /v1/dids/stellar/{did}/transfer with { expectedVersion, newController, sourcePublicKey }.
• Deactivate: POST /v1/dids/stellar/{did}/deactivate with { expectedVersion, sourcePublicKey }. Afterwards the DID resolves with 410.

Prepare/Submit

Mode is selected by the body: with signedXdr present, the route submits; without it, the route validates and returns the unsigned xdr plus the network passphrase. The controller's Stellar wallet signs the transaction envelope; DID keys inside the record are separate material (they sign credentials and Proof of Control challenges, never the registration transaction).

Rate limits & errors

• Per-IP rate limit: 120 requests per 60 seconds by default, with X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After headers; 429 returns { "code": "rate_limited" }.
• Every error uses a stable envelope { code, message, details? } where code is a machine-readable string shared with the TypeScript library (e.g. did_invalid, did_already_exists, version_mismatch, did_deactivated, tx_submission_failed). Branch on code, never on message.
• Requests carry an X-Request-ID correlation header, echoed back in responses.