From 103ce00810f7766c59c7c15c51c25d4152c44441 Mon Sep 17 00:00:00 2001 From: pselle Date: Thu, 22 Oct 2026 21:23:24 -0400 Subject: [PATCH 1/2] docs: add account names to the Registry guide Co-Authored-By: Claude --- docs/site/docs/registry.md | 63 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/site/docs/registry.md b/docs/site/docs/registry.md index 0436e2c2..88ca5fb8 100644 --- a/docs/site/docs/registry.md +++ b/docs/site/docs/registry.md @@ -30,6 +30,8 @@ The Registry smart contract keeps track of two kinds of information: So that's it, at its core: Stellar Registry is a smart contract, which gives other smart contracts names, and which gives Wasms both names and versions. +It can also give names to accounts: see [Accounts](#accounts). + ### Quick Links Around the core smart contract, Stellar Registry wraps other tooling: @@ -91,6 +93,8 @@ Names in the registry support namespace prefixes. The CLI resolves names using t - `unverified/my-contract` - First fetches the `unverified` registry contract ID from the root registry, then looks up `my-contract` in that registry - `some-other-subregistry/my-contract` — Same as above. Looks up `some-other-subregistry` in the root registry, then looks up `my-contract` in that registry. +Account names resolve the same way, but in their own namespace: `unverified/alice` is the account named `alice` in the `unverified` registry, even if a contract is also named `alice` there. + ### Name Normalization All names are normalized by the [stellar-registry-name](https://crates.io/crates/stellar-registry-name) crate before storage: @@ -323,6 +327,65 @@ stellar contract invoke --id -- \ --contract-name ``` +## Accounts + +Besides Wasms and Contracts, a Registry can name accounts: a classic Stellar account (G-address) or a smart account (a C-address backed by a Wasm contract, not a Stellar Asset Contract). Account names live in a separate namespace from contract names, and follow the same [normalization](#name-normalization) rules. + +Like a contract name, an account name has an owner, who can rename it, point it at a different address, transfer it, or flag it as compromised. + +### Consent + +You can't put a name on someone else's address without their agreement. Registering a name for an address (and renaming it, or pointing a name at a new address) needs that address's consent, given one of two ways: + +1. **It signs the transaction.** This is implied when the address is the one submitting it, e.g. naming your own account. +2. **It preauthorized the name beforehand** with `preauthorize-account`, for a specific name _and_ owner. A preauthorization is single-use, expires after about 180 days on Mainnet, can be withdrawn with `revoke-account-preauth`, and doesn't reserve the name: registration is still first come, first served. + +The CLI can't sign for a smart account. A smart account has to preauthorize from its own wallet, by calling the Registry's `preauthorize_account` function. + +### Managed and Unmanaged Registries + +On the unmanaged `unverified` registry, you can register an account name yourself, as long as the account consents: + +```bash +stellar registry register-account \ + --account-name unverified/alice \ + --account-address alice +``` + +Passing a local identity (`alice`, as created with `stellar keys`) as the address lets it sign the transaction. + +On a managed registry, like the root, the manager executes the registration via the [governance process](#quick-links), and that call can't carry the account's signature. So the account preauthorizes first, naming the owner the governance request is for: + +```bash +stellar registry preauthorize-account \ + --account-name alice \ + --account-address alice \ + --owner \ + --source alice +``` + +Then open the governance request. If a command would fail for lack of consent, the CLI stops before submitting and prints the `preauthorize-account` command to run. + +### Account Commands + +| Command | Purpose | Key options | +| --- | --- | --- | +| `register-account` | Name an account | `--account-name`, `--account-address` (G-address, C-address, or identity alias), `--owner` (defaults to source), `--dry-run` | +| `preauthorize-account` | Consent in advance to being named; signed by the account | `--account-name`, `--account-address`, `--owner` (defaults to source), `--dry-run` | +| `revoke-account-preauth` | Withdraw a pending preauthorization; signed by the account | `--account-name`, `--account-address`, `--dry-run` | +| `fetch-account-id ` | Look up a named account's address | `--force` (return it even if flagged as compromised) | +| `fetch-account-owner ` | Look up who owns an account name | | +| `rename-account` | Rename an account; it must consent to the new name | `--account-name`, `--new-name`, `--dry-run` | +| `update-account-address` | Point a name at a different address, which must consent | `--account-name`, `--new-address`, `--dry-run` | +| `update-account-owner` | Transfer ownership of an account name | `--account-name`, `--new-owner`, `--dry-run` | +| `flag-account` | Flag an account as compromised, or clear the flag | `--account-name`, `--unflag`, `--dry-run` | + +All `--account-name` values support prefix notation like `unverified/alice`. For example: + +```bash +stellar registry fetch-account-id unverified/alice +``` + ## Configuration The registry CLI respects the following environment variables: From 42d67e963ec8083829565494374fed653d46d96f Mon Sep 17 00:00:00 2001 From: pselle Date: Sat, 24 Oct 2026 23:24:25 +0100 Subject: [PATCH 2/2] docs: match account commands to stellar-registry-cli v0.2.0 The account commands shipped under `stellar registry account`, and there is no flag-account command; flagging goes through `contract invoke`. Co-Authored-By: Claude --- docs/site/docs/registry.md | 38 ++++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/docs/site/docs/registry.md b/docs/site/docs/registry.md index 88ca5fb8..4a5edb4c 100644 --- a/docs/site/docs/registry.md +++ b/docs/site/docs/registry.md @@ -338,7 +338,7 @@ Like a contract name, an account name has an owner, who can rename it, point it You can't put a name on someone else's address without their agreement. Registering a name for an address (and renaming it, or pointing a name at a new address) needs that address's consent, given one of two ways: 1. **It signs the transaction.** This is implied when the address is the one submitting it, e.g. naming your own account. -2. **It preauthorized the name beforehand** with `preauthorize-account`, for a specific name _and_ owner. A preauthorization is single-use, expires after about 180 days on Mainnet, can be withdrawn with `revoke-account-preauth`, and doesn't reserve the name: registration is still first come, first served. +2. **It preauthorized the name beforehand** with `account preauthorize`, for a specific name _and_ owner. A preauthorization is single-use, expires after about 180 days on Mainnet, can be withdrawn with `account revoke-preauth`, and doesn't reserve the name: registration is still first come, first served. The CLI can't sign for a smart account. A smart account has to preauthorize from its own wallet, by calling the Registry's `preauthorize_account` function. @@ -347,7 +347,7 @@ The CLI can't sign for a smart account. A smart account has to preauthorize from On the unmanaged `unverified` registry, you can register an account name yourself, as long as the account consents: ```bash -stellar registry register-account \ +stellar registry account register \ --account-name unverified/alice \ --account-address alice ``` @@ -357,33 +357,43 @@ Passing a local identity (`alice`, as created with `stellar keys`) as the addres On a managed registry, like the root, the manager executes the registration via the [governance process](#quick-links), and that call can't carry the account's signature. So the account preauthorizes first, naming the owner the governance request is for: ```bash -stellar registry preauthorize-account \ +stellar registry account preauthorize \ --account-name alice \ --account-address alice \ --owner \ --source alice ``` -Then open the governance request. If a command would fail for lack of consent, the CLI stops before submitting and prints the `preauthorize-account` command to run. +Then open the governance request. If a command would fail for lack of consent, the CLI stops before submitting and prints the `account preauthorize` command to run. ### Account Commands +The account commands are grouped under `stellar registry account`: + | Command | Purpose | Key options | | --- | --- | --- | -| `register-account` | Name an account | `--account-name`, `--account-address` (G-address, C-address, or identity alias), `--owner` (defaults to source), `--dry-run` | -| `preauthorize-account` | Consent in advance to being named; signed by the account | `--account-name`, `--account-address`, `--owner` (defaults to source), `--dry-run` | -| `revoke-account-preauth` | Withdraw a pending preauthorization; signed by the account | `--account-name`, `--account-address`, `--dry-run` | -| `fetch-account-id ` | Look up a named account's address | `--force` (return it even if flagged as compromised) | -| `fetch-account-owner ` | Look up who owns an account name | | -| `rename-account` | Rename an account; it must consent to the new name | `--account-name`, `--new-name`, `--dry-run` | -| `update-account-address` | Point a name at a different address, which must consent | `--account-name`, `--new-address`, `--dry-run` | -| `update-account-owner` | Transfer ownership of an account name | `--account-name`, `--new-owner`, `--dry-run` | -| `flag-account` | Flag an account as compromised, or clear the flag | `--account-name`, `--unflag`, `--dry-run` | +| `register` | Name an account | `--account-name`, `--account-address` (G-address, C-address, or identity alias), `--owner` (defaults to source), `--dry-run` | +| `preauthorize` | Consent in advance to being named; signed by the account | `--account-name`, `--account-address`, `--owner` (defaults to source), `--dry-run` | +| `revoke-preauth` | Withdraw a pending preauthorization; signed by the account | `--account-name`, `--account-address`, `--dry-run` | +| `fetch-id ` | Look up a named account's address | `--force` (return it even if flagged as compromised) | +| `fetch-owner ` | Look up who owns an account name | | +| `rename` | Rename an account; it must consent to the new name | `--account-name`, `--new-name`, `--dry-run` | +| `update-address` | Point a name at a different address, which must consent | `--account-name`, `--new-address`, `--dry-run` | +| `update-owner` | Transfer ownership of an account name | `--account-name`, `--new-owner`, `--dry-run` | All `--account-name` values support prefix notation like `unverified/alice`. For example: ```bash -stellar registry fetch-account-id unverified/alice +stellar registry account fetch-id unverified/alice +``` + +There's no CLI command for flagging an account. The owner or the registry's manager flags it, or clears the flag, by invoking the Registry directly: + +```bash +stellar contract invoke --id -- \ + flag_account \ + --account-name \ + --flagged true ``` ## Configuration