feat(registry): subname registration under parent names #4

💠 Sidera — Stellar Name Service. Contribute via Drips Wave / GrantFox. Comment with your approach and wait for assignment before starting.

Description

Every payment app on Stellar could issue names to its users (bob.qiuckex.sid) instead of making them compete for top-level names. The registry stores bare names only — there is no hierarchy. Subnames turn every registrant into a distribution channel and are the adoption engine for the whole protocol.

Desired outcome: a name owner can register subnames under their name (register_subname(parent, sub, owner, address, memo)), bounded by a per-parent cap to keep storage bounded; subnames resolve like top-level names via their full dotted key.

Scope

• Crate/module: crates/registry, src/lib.rs
• API: register_subname(parent, sub, owner, address, memo), set_subname_address(parent, sub, ...), unset_subname(parent, sub); resolve accepts dotted input (bob.parent.sid → key bob.parent)
• Storage: subnames stored as full-string keys ("bob.parent") in the same DataKey::Name namespace — no new key shape; parent gains a SubCount instance key
• Tests: owner-auth on parent for all three entrypoints; cap enforcement (MAX_SUBNAMES_PER_PARENT); sub of missing parent → NotFound; subname resolves via dotted resolve; validate_name extended (dots only as separators, no empty labels); subname cannot itself be a parent (one level only — documented)
• Docs: subname section + updated validation rules

Non-goals

• Multi-level nesting (a.b.c.sid) — one level only for this tranche
• Subname fees (inheritance of pricing is a later design decision)
• Subname transfer independent of parent
• Off-chain subnames (L2/merkle approaches)

What "done" looks like

• register_subname requires parent-owner auth; stores key "{sub}.{parent}"
• Parent SubCount enforced against a documented MAX_SUBNAMES_PER_PARENT constant; exceeding → new SubnameCapReached error (next free code)
• resolve("bob.parent") (and dotted resolve input with .sid stripped) returns the subname record
• unset_subname deletes the record and decrements the count; owner-auth required
• Existing names unaffected; validate_name rejects malformed dotted input (empty labels, leading/trailing dots)
• New tests: cap, auth, dotted resolution, validation matrix
• All gates pass

Implementation guidelines

• Keep subnames in the SAME DataKey::Name(String) map — dotted keys make resolve uniform and avoid a second storage class
• total_names semantics decision: count only top-level names (document it) — subnames get sub_count(parent)
• Dot-handling belongs in validate_name's caller: split input into labels, validate each with the existing 3–32/charset rule except the LAST label (sub label may be shorter? — document your choice, min 1–2 chars is defensible)
• TTL: subname writes extend their own keys; parent-owner check reads the parent's Owner key (existing TTL rules apply)

Verification

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test -p sidera-registry --all-targets --locked

PR guidelines

• Get assigned before starting; do not start work on a reserved issue.
• Work in a fork; branch off upstream/main; open the PR against Sidera-Protocol/sidera-contracts:main.
• PR description must include Closes #4.
• All CI checks must pass; human maintainer review required.

Metadata

• Affected crates/files: contracts/registry/src/lib.rs, docs/
• Complexity label: complexity: medium (150 base points)
• Type labels: enhancement