# node-families-contract Specification

## Purpose
TBD - created by archiving change node-families-contract-spec. Update Purpose after archive.
## Requirements
### Requirement: Contract instantiation persists the runtime config, mixnet contract address, and admin

The contract SHALL be instantiable exactly once via the standard CosmWasm `instantiate` entry point. The instantiation message SHALL carry a `Config` (creation fee, family-name length limit, family-description length limit, default invitation validity in seconds) and a string-form `mixnet_contract_address`. The handler MUST:

- bech32-validate `mixnet_contract_address` and reject malformed inputs;
- persist the validated mixnet contract address, the `Config`, and `info.sender` as the contract admin;
- record the contract name and `CARGO_PKG_VERSION` via `cw2::set_contract_version`;
- record build information via `set_build_information!`.

#### Scenario: Valid instantiation persists config, mixnet address, and admin
- **WHEN** `instantiate` is called with a valid bech32 mixnet contract address and a well-formed `Config`
- **THEN** the contract stores the `Config` verbatim, the validated `Addr` for the mixnet contract, and sets `info.sender` as the contract admin queryable via `cw-controllers::Admin::assert_admin`
- **AND** `cw2::get_contract_version` returns the crate's `CARGO_PKG_VERSION`

#### Scenario: Invalid mixnet contract address is rejected
- **WHEN** `instantiate` is called with a `mixnet_contract_address` string that fails `Addr::validate`
- **THEN** the call returns an error and no state is persisted

### Requirement: Migration entry point forbids version downgrades

The contract SHALL expose a `migrate` entry point that refreshes recorded build information and uses `cw2::ensure_from_older_version` to guarantee the on-chain contract version is at most the current `CARGO_PKG_VERSION`. Downgrade attempts MUST be rejected.

#### Scenario: Equal or older on-chain version is accepted
- **WHEN** `migrate` is called against an on-chain `cw2` version less than or equal to `CARGO_PKG_VERSION`
- **THEN** the call succeeds and `set_build_information!` updates the stored build metadata

#### Scenario: Newer on-chain version is rejected
- **WHEN** `migrate` is called against an on-chain `cw2` version strictly greater than `CARGO_PKG_VERSION`
- **THEN** the call returns an error and storage is unchanged

### Requirement: Only the contract admin can replace the runtime config

The `ExecuteMsg::UpdateConfig` handler SHALL overwrite the stored `Config` with the value supplied by the caller. The handler MUST call `Admin::assert_admin` and return the underlying `AdminError` (wrapped in `NodeFamiliesContractError::Admin`) when the sender is not the admin.

#### Scenario: Admin replaces the config
- **WHEN** the contract admin sends `ExecuteMsg::UpdateConfig { config }`
- **THEN** the stored `Config` equals the supplied value on subsequent reads

#### Scenario: Non-admin is rejected
- **WHEN** a non-admin sender sends `ExecuteMsg::UpdateConfig`
- **THEN** the call returns an `Admin` error and the stored `Config` is unchanged

### Requirement: Family names are normalised and globally unique under their normalised form

Family names SHALL be normalised to a canonical form by lowercasing ASCII letters, preserving ASCII digits, and dropping every other character (whitespace, punctuation, non-ASCII letters). The normalised form SHALL be stored alongside the user-supplied `name` and SHALL be the key of the `families.normalised_name` unique index. Inputs whose normalised form is the empty string SHALL be rejected with `EmptyFamilyName`. Inputs whose original length exceeds `Config::family_name_length_limit` (measured in **bytes**, via `String::len`) SHALL be rejected with `FamilyNameTooLong { length, limit }`. Creation of a family whose normalised name collides with an existing family SHALL fail with `FamilyNameAlreadyTaken { name, family_id }`.

**Important**: this normalisation is ASCII-only by design. Non-ASCII letters and emoji are stripped entirely (`"café"` → `"caf"`, `"名前"` → `""`, `"⭐stars"` → `"stars"`). Names consisting solely of non-ASCII characters or symbols are rejected as `EmptyFamilyName`. Operators who want a non-ASCII brand cannot encode it in the on-chain family name; the user-supplied `name` field preserves the original formatting but only the normalised ASCII form is enforced for uniqueness and emptiness.

#### Scenario: Normalisation strips punctuation, whitespace, casing, and non-ASCII letters
- **WHEN** the contract normalises any of `"Foo Bar"`, `"foobar"`, `"FOO-BAR"`, or `"  f.o.o.b.a.r  "`
- **THEN** every result equals `"foobar"`

#### Scenario: All-symbol name is rejected
- **WHEN** `CreateFamily` is sent with `name = "!!!---"` (normalises to the empty string)
- **THEN** the call fails with `EmptyFamilyName` and no family is persisted

#### Scenario: Name length is checked against the original string, not the normalised form
- **WHEN** `CreateFamily` is sent with a `name` whose `name.len()` (byte length) exceeds `Config::family_name_length_limit`
- **THEN** the call fails with `FamilyNameTooLong { length, limit }`

#### Scenario: Multi-byte characters count their full byte length toward the limit
- **WHEN** `Config::family_name_length_limit = 8` and `CreateFamily` is sent with `name = "🚀rocket"` (a 4-byte emoji followed by `"rocket"`, totalling `name.len() == 10` bytes — but only 7 user-perceived characters)
- **THEN** the call fails with `FamilyNameTooLong { length: 10, limit: 8 }` even though the visible character count is within the limit
- **AND** had the limit been `>= 10`, the name would have been accepted and the normalised form would be `"rocket"` (the emoji dropped during normalisation)

#### Scenario: Two formattings of the same canonical name collide
- **WHEN** family `A` is created with `name = "Shared"` and `B` later tries to create with `name = "$$shared$$"`
- **THEN** the second call fails with `FamilyNameAlreadyTaken { name: "shared", family_id: A.id }`

### Requirement: An address may own at most one family at a time

A given owner address SHALL own at most one family at any time, enforced by the `families.owner` unique index. `CreateFamily` SHALL pre-check this and fail with `SenderAlreadyOwnsAFamily { address, family_id }` for better error context. The pre-check is in addition to (not instead of) the unique-index defence-in-depth check. Owner-gated handlers (`DisbandFamily`, `InviteToFamily`, `RevokeFamilyInvitation`, `KickFromFamily`) SHALL look up the family by owner and fail with `SenderDoesntOwnAFamily { address }` when none exists.

#### Scenario: Same address cannot create a second family while still owning one
- **WHEN** address `alice` already owns family `A` and `CreateFamily` is sent again with `alice` as sender
- **THEN** the call fails with `SenderAlreadyOwnsAFamily { address: alice, family_id: A.id }`

#### Scenario: Address can create a family again after disbanding its previous one
- **WHEN** `alice` creates family `A` then disbands it, then sends `CreateFamily` again
- **THEN** a new family with a strictly greater id than `A` is created (ids are monotonic and never recycled)

#### Scenario: Owner-gated handler rejects a sender that owns no family
- **WHEN** any of `DisbandFamily`, `InviteToFamily`, `RevokeFamilyInvitation`, or `KickFromFamily` is sent by an address that owns no family
- **THEN** the call fails with `SenderDoesntOwnAFamily { address }`

### Requirement: Family creation requires the configured fee and is rejected if the owner's bonded node is already in a family

`ExecuteMsg::CreateFamily` SHALL require the sender to attach exactly one coin matching `Config::create_family_fee` in both denom and amount. Payment validation MUST go through `cw_utils::must_pay`; mismatches in amount MUST surface as `InvalidFamilyCreationFee { expected, received }`. The handler MUST additionally check that any bonded node the sender controls (as reported by the mixnet contract via `query_nymnode_ownership`) is not currently a member of any family, failing with `AlreadyInFamily { address, node_id, family_id }` otherwise. The handler MUST validate the description length against `Config::family_description_length_limit` and reject overlong descriptions with `FamilyDescriptionTooLong { length, limit }`. On success the handler SHALL emit a `family_creation` event with attributes `family_name`, `owner_address`, `family_id`, `paid_fee`.

#### Scenario: Successful family creation persists the family and emits the event
- **WHEN** a sender with no bonded family-member node and no existing-owned family sends `CreateFamily { name, description }` with the correct fee attached
- **THEN** a new family is persisted with monotonically increasing `id`, the supplied `name` and `description`, the computed `normalised_name`, `members = 0`, `created_at = env.block.time.seconds()`, and `paid_fee` equal to the configured fee
- **AND** the response carries an event named `family_creation` with attributes `family_name`, `owner_address`, `family_id`, `paid_fee`

#### Scenario: Wrong fee denom or missing funds is rejected
- **WHEN** `CreateFamily` is sent with no funds, with multiple denoms, or with a denom different from `Config::create_family_fee.denom`
- **THEN** the call fails with `InvalidDeposit(PaymentError)`

#### Scenario: Wrong fee amount is rejected
- **WHEN** `CreateFamily` is sent with the correct denom but an amount different from `Config::create_family_fee.amount`
- **THEN** the call fails with `InvalidFamilyCreationFee { expected, received }` and the funds remain unspent

#### Scenario: Sender whose bonded node is already in a family is rejected
- **WHEN** `CreateFamily` is sent by an address whose bonded node (per the mixnet contract) is already a member of some family `F`
- **THEN** the call fails with `AlreadyInFamily { address, node_id, family_id: F.id }`

#### Scenario: Overlong description is rejected
- **WHEN** `CreateFamily` is sent with a `description` whose byte length exceeds `Config::family_description_length_limit`
- **THEN** the call fails with `FamilyDescriptionTooLong { length, limit }`

### Requirement: A family's name and/or description can be updated by its owner

`ExecuteMsg::UpdateFamily { updated_name: Option<String>, updated_description: Option<String> }` SHALL allow the owner of an existing family to replace either or both fields independently. Each argument follows `None = keep` / `Some(_) = replace` semantics; a call carrying `None` for both fields SHALL be a silent no-op (empty `Response`, no event, no state change) and SHALL short-circuit BEFORE the owner-ownership check (so a sender that owns no family can also no-op without error). Otherwise the handler MUST look up the sender's family via the `owner` unique index and fail with `SenderDoesntOwnAFamily { address }` if none exists. Updated values MUST be validated against the same rules as `CreateFamily`: a `Some(name)` MUST satisfy `Config::family_name_length_limit` (else `FamilyNameTooLong { length, limit }`) and MUST normalise to a non-empty string (else `EmptyFamilyName`); a `Some(description)` MUST satisfy `Config::family_description_length_limit` (else `FamilyDescriptionTooLong { length, limit }`). The new normalised name MUST be globally unique against OTHER families (else `FamilyNameAlreadyTaken { name, family_id }`); a name change whose normalised form matches the family's own existing `normalised_name` (a case-only or punctuation-only rename) MUST be allowed. The handler MUST preserve `id`, `owner`, `paid_fee`, `members`, and `created_at`. On a state-changing success the response SHALL include a `family_update` event with `family_id` and `owner_address` attributes plus conditional `updated_name` / `updated_description` attributes for each field actually changed by the call.

#### Scenario: Owner updates the family name only
- **WHEN** the family owner sends `UpdateFamily { updated_name: Some(n), updated_description: None }` with a valid `n`
- **THEN** the persisted family's `name` and `normalised_name` are replaced with `n` and its normalised form, while `description`, `id`, `owner`, `paid_fee`, `members`, and `created_at` are unchanged
- **AND** the response carries a `family_update` event with `family_id`, `owner_address`, and `updated_name = n` (no `updated_description` attribute)

#### Scenario: Owner updates the description only
- **WHEN** the family owner sends `UpdateFamily { updated_name: None, updated_description: Some(d) }` with a valid `d`
- **THEN** the persisted family's `description` is replaced with `d` and every other field is unchanged
- **AND** the response carries a `family_update` event with `family_id`, `owner_address`, and `updated_description = d` (no `updated_name` attribute)

#### Scenario: Owner updates both fields
- **WHEN** the family owner sends `UpdateFamily { updated_name: Some(n), updated_description: Some(d) }` with both values valid
- **THEN** both `name`/`normalised_name` and `description` are replaced, and the event carries both `updated_name` and `updated_description` attributes

#### Scenario: A fully-empty call is a silent no-op for any sender
- **WHEN** any sender (whether or not they own a family) sends `UpdateFamily { updated_name: None, updated_description: None }`
- **THEN** the response is `Response::default()` (no events, no messages) and storage is unchanged

#### Scenario: Sender that owns no family is rejected when at least one field is set
- **WHEN** an address that does not own any family sends `UpdateFamily` with at least one `Some(_)` field
- **THEN** the call fails with `SenderDoesntOwnAFamily { address }`

#### Scenario: Overlong name is rejected
- **WHEN** `UpdateFamily { updated_name: Some(n), .. }` is sent with `n.len() > Config::family_name_length_limit`
- **THEN** the call fails with `FamilyNameTooLong { length, limit }` and storage is unchanged

#### Scenario: Name normalising to empty is rejected
- **WHEN** `UpdateFamily { updated_name: Some(n), .. }` is sent with an `n` whose normalisation yields the empty string
- **THEN** the call fails with `EmptyFamilyName` and storage is unchanged

#### Scenario: Renaming to another family's normalised name is rejected
- **WHEN** family `A`'s owner sends `UpdateFamily { updated_name: Some(n), .. }` whose normalisation equals a different family `B`'s `normalised_name`
- **THEN** the call fails with `FamilyNameAlreadyTaken { name, family_id: B.id }` and storage is unchanged

#### Scenario: Case-only or punctuation-only rename is allowed
- **WHEN** the owner sends `UpdateFamily { updated_name: Some(n), .. }` whose normalisation equals the family's own existing `normalised_name`
- **THEN** the display `name` is replaced with `n`, the `normalised_name` is unchanged, and the call succeeds

#### Scenario: Overlong description is rejected
- **WHEN** `UpdateFamily { updated_description: Some(d), .. }` is sent with `d.len() > Config::family_description_length_limit`
- **THEN** the call fails with `FamilyDescriptionTooLong { length, limit }` and storage is unchanged

### Requirement: Family ids are monotonic, never recycled, and start at 1

The contract SHALL assign family ids sequentially starting at `1`. The id counter SHALL be persisted as an `Item<NodeFamilyId>` and incremented on each successful family creation. Disbanding a family MUST NOT free or recycle its id. `0` SHALL be reserved as a "no family" sentinel and never assigned.

#### Scenario: First-ever family receives id 1
- **WHEN** the contract is freshly instantiated and the first successful `CreateFamily` runs
- **THEN** the persisted `NodeFamily.id` equals `1`

#### Scenario: Ids are not reused after disband
- **WHEN** family with id `N` is disbanded and a new family is then created
- **THEN** the new family's id is strictly greater than `N` (it is `N+1` if no other families were created in between)

### Requirement: A family can only be disbanded by its owner, must be empty, and refunds the creation fee

`ExecuteMsg::DisbandFamily` SHALL look up the sender's family via the `owner` unique index and fail with `SenderDoesntOwnAFamily` when none exists. The handler MUST reject disbanding while `NodeFamily.members > 0`, failing with `FamilyNotEmpty { family_id, members }`. On success the handler SHALL sweep every still-pending invitation issued by the family (archiving each as `FamilyInvitationStatus::Revoked { at: now }` with status timestamp = `env.block.time.seconds()`), remove the family record, and attach a `BankMsg::Send { to_address: owner, amount: vec![family.paid_fee] }` to the response as a CosmWasm sub-message. The response SHALL include a `family_disband` event with `family_id`, `owner_address`, `refunded_fee` attributes.

**Operational note (non-normative)**: the pending-invitation sweep iterates every entry of `pending_family_invitations` keyed by `family_id` and archives each in a single transaction. Gas cost therefore scales linearly with the number of leftover pending invitations. An owner whose family has accumulated an unusually large number of pending invitations is expected to revoke them in batches (via `RevokeFamilyInvitation`) *before* invoking `DisbandFamily`, since a single disband call that exceeds the per-tx gas limit will fail and leave the family in place. There is no contract-side chunking; the responsibility lies with the caller.

#### Scenario: Owner disbands an empty family and is refunded
- **WHEN** family owner sends `DisbandFamily` while `members == 0`
- **THEN** the family is removed from storage, the response carries a `BankMsg::Send` of `family.paid_fee` to the owner, and a `family_disband` event is emitted

#### Scenario: Refund is attached as a BankMsg::Send sub-message, not a direct bank-module call
- **WHEN** a successful `DisbandFamily` returns its `Response`
- **THEN** the response's `messages` field contains exactly one `CosmosMsg::Bank(BankMsg::Send { to_address: <owner bech32>, amount: vec![<family.paid_fee>] })` and the contract performs no other balance-changing side effect for the refund
- **AND** tx simulators that inspect outbound sub-messages observe the refund there (this is the contract's only avenue for returning funds; integrators rely on it)

#### Scenario: Non-empty family cannot be disbanded
- **WHEN** family owner sends `DisbandFamily` while `members > 0`
- **THEN** the call fails with `FamilyNotEmpty { family_id, members }` and storage is unchanged

#### Scenario: Disbanding sweeps still-pending invitations as Revoked
- **WHEN** family `F` has pending invitations to nodes `n1`, `n2` and the owner sends `DisbandFamily`
- **THEN** the pending entries for `(F.id, n1)` and `(F.id, n2)` are removed from `pending_family_invitations` and archived under `past_family_invitations` with `status = Revoked { at: env.block.time.seconds() }`

### Requirement: A node belongs to at most one family at any time

The `family_members` map SHALL be keyed by `NodeId` alone; the value SHALL carry the `family_id` so the storage layer enforces the one-family-per-node invariant by construction. Handlers that add a membership (`AcceptFamilyInvitation`) and handlers that issue an invitation (`InviteToFamily`) SHALL pre-check the absence of any existing membership for the node and fail with `NodeAlreadyInFamily { node_id, family_id }` otherwise.

#### Scenario: Inviting a node already in a family is rejected
- **WHEN** `InviteToFamily { node_id }` targets a node that already has a membership record for family `F`
- **THEN** the call fails with `NodeAlreadyInFamily { node_id, family_id: F.id }`

#### Scenario: Accepting a second invitation after joining a family is rejected
- **WHEN** node `n` is a member of family `F` and `AcceptFamilyInvitation { family_id: G, node_id: n }` is sent (for a different family `G`)
- **THEN** the call fails with `NodeAlreadyInFamily { node_id: n, family_id: F.id }`

### Requirement: Invitations require an existing family, a bonded target node, and strictly positive validity

`ExecuteMsg::InviteToFamily` SHALL be owner-gated (the family acted on is the sender's owned family, never an argument). The handler MUST:

- compute `validity = validity_secs.unwrap_or(Config::default_invitation_validity_secs)`;
- reject `validity == 0` with `ZeroInvitationValidity`;
- verify `node_id` refers to a currently-bonded, not-unbonding node in the mixnet contract via `MixnetContractQuerier::check_node_existence` (which returns `false` both when no bond exists and when the bond is in the unbonding state), failing with `NodeDoesntExist { node_id }` otherwise;
- verify the node is not already in any family (see "A node belongs to at most one family");
- reject `(family_id, node_id)` pairs that already have a **still-valid** pending invitation (`env.block.time.seconds() < existing.expires_at`) with `PendingInvitationAlreadyExists { family_id, node_id }`;
- when a pending invitation for the pair exists but has already expired (`env.block.time.seconds() >= existing.expires_at`), archive it as `PastFamilyInvitation { invitation, status: Expired { at: env.block.time.seconds() } }` using the next free per-`(family, node)` archive slot, then let the fresh invitation supersede it;
- persist a `FamilyInvitation` with `expires_at = env.block.time.seconds() + validity`;
- emit a `family_invitation` event with `family_id`, `node_id`, `expires_at` (the same event whether or not it superseded an expired invitation).

#### Scenario: Successful invitation persists with the computed expiry
- **WHEN** family owner sends `InviteToFamily { node_id, validity_secs: Some(v) }` and all preconditions hold
- **THEN** a pending invitation for `(owned.id, node_id)` is persisted with `expires_at = env.block.time.seconds() + v`
- **AND** the response carries a `family_invitation` event with `family_id = owned.id`, `node_id`, `expires_at`

#### Scenario: Missing validity falls back to the configured default
- **WHEN** `InviteToFamily { node_id, validity_secs: None }` is sent
- **THEN** the persisted invitation has `expires_at = env.block.time.seconds() + Config::default_invitation_validity_secs`

#### Scenario: Zero validity is rejected
- **WHEN** `InviteToFamily { node_id, validity_secs: Some(0) }` is sent
- **THEN** the call fails with `ZeroInvitationValidity` and no invitation is persisted

#### Scenario: Inviting a non-bonded node is rejected
- **WHEN** `InviteToFamily { node_id }` targets a `node_id` for which the mixnet contract's `check_node_existence` returns `false`
- **THEN** the call fails with `NodeDoesntExist { node_id }`

#### Scenario: Duplicate still-valid pending invitation is rejected
- **WHEN** family `F` already has a still-valid (not yet expired) pending invitation for node `n` and `InviteToFamily { node_id: n }` is sent again by `F`'s owner
- **THEN** the call fails with `PendingInvitationAlreadyExists { family_id: F.id, node_id: n }` (the existing invitation is preserved and nothing is archived)

#### Scenario: Re-inviting after the previous invitation expired supersedes it
- **WHEN** family `F` has a pending invitation for node `n` whose `expires_at <= env.block.time.seconds()` and `InviteToFamily { node_id: n }` is sent again by `F`'s owner
- **THEN** the call succeeds: the stale invitation is archived under `past_family_invitations` with `status = Expired { at: env.block.time.seconds() }`, and a fresh `FamilyInvitation` for `(F.id, n)` is persisted with the newly computed `expires_at`

### Requirement: Acceptance and rejection of an invitation are gated on node control

`ExecuteMsg::AcceptFamilyInvitation` and `ExecuteMsg::RejectFamilyInvitation` SHALL each verify that the sender is the controller of the bonded node `node_id` per the mixnet contract (`query_nymnode_ownership` returns a `nym_node` with `node_id == node_id` and `is_unbonding == false`). Failures MUST surface as `SenderDoesntControlNode { address, node_id }`. This single error covers the cases of: sender owns no bonded node, sender owns a different node id, and sender owns the node but it has entered unbonding.

#### Scenario: Non-controller cannot accept an invitation
- **WHEN** `AcceptFamilyInvitation { family_id, node_id }` is sent by an address that does not control `node_id` (per mixnet contract)
- **THEN** the call fails with `SenderDoesntControlNode { address, node_id }`

#### Scenario: Unbonding node cannot accept an invitation
- **WHEN** the sender controls `node_id` but the mixnet contract reports the node as unbonding
- **THEN** `AcceptFamilyInvitation` fails with `SenderDoesntControlNode { address, node_id }`

#### Scenario: Non-controller cannot reject an invitation
- **WHEN** `RejectFamilyInvitation { family_id, node_id }` is sent by an address that does not control `node_id`
- **THEN** the call fails with `SenderDoesntControlNode { address, node_id }`

### Requirement: Accepting an invitation moves it from pending to archived and increments the family member count

A successful `AcceptFamilyInvitation` SHALL:

- load the pending invitation for `(family_id, node_id)`, failing with `InvitationNotFound { family_id, node_id }` if absent;
- check `now < invitation.expires_at`, failing with `InvitationExpired { family_id, node_id, expires_at, now }` otherwise (`now == expires_at` is considered expired);
- remove the entry from `pending_family_invitations`;
- write `family_members[node_id] = FamilyMembership { family_id, joined_at: now }`;
- increment `NodeFamily::members` by 1 (failing with `FamilyNotFound { family_id }` if the family has somehow been removed);
- archive a `PastFamilyInvitation { invitation, status: Accepted { at: now } }` under `((family_id, node_id), counter)` where `counter` is the next free per-`(family, node)` archive slot;
- emit a `family_invitation_accepted` event with `family_id`, `node_id`.

#### Scenario: Happy-path acceptance
- **WHEN** node controller accepts a not-yet-expired pending invitation
- **THEN** the membership is recorded with `joined_at = env.block.time.seconds()`, the family's `members` count is incremented, the pending entry is removed, and the archive contains the invitation with status `Accepted { at: now }`

#### Scenario: Acceptance of an already-expired invitation is rejected
- **WHEN** `AcceptFamilyInvitation` is called with `env.block.time.seconds() >= invitation.expires_at`
- **THEN** the call fails with `InvitationExpired { family_id, node_id, expires_at, now }` and storage is unchanged

#### Scenario: Acceptance with no pending invitation is rejected
- **WHEN** `AcceptFamilyInvitation { family_id, node_id }` is called with no pending invitation stored for that pair
- **THEN** the call fails with `InvitationNotFound { family_id, node_id }`

### Requirement: Rejection and revocation work on expired invitations and archive them with terminal status

`RejectFamilyInvitation` (sent by the node controller) and `RevokeFamilyInvitation` (sent by the family owner) SHALL each:

- remove the pending invitation;
- archive a `PastFamilyInvitation` with status `Rejected { at: now }` or `Revoked { at: now }` respectively, under `((family_id, node_id), counter)` using the next free per-`(family, node)` archive slot;
- emit `family_invitation_rejected` or `family_invitation_revoked` respectively, with `family_id` and `node_id` attributes;
- fail with `InvitationNotFound { family_id, node_id }` if no pending invitation exists.

The contract performs no background sweep of expired entries. Reject and revoke are the two *targeted* ways to clear a specific pending invitation; an expired one is additionally cleared if the family owner re-invites the same node (archiving the stale entry as `Expired { at: now }` before superseding it — see "Invitations require an existing family …") or if the family is disbanded.

#### Scenario: Owner revokes a still-pending invitation
- **WHEN** family owner sends `RevokeFamilyInvitation { node_id }` for a node currently in their pending invitations
- **THEN** the pending entry is removed and the archive contains the invitation with status `Revoked { at: env.block.time.seconds() }`

#### Scenario: Node controller rejects a still-pending invitation
- **WHEN** node controller sends `RejectFamilyInvitation { family_id, node_id }` for a pending invitation
- **THEN** the pending entry is removed and the archive contains the invitation with status `Rejected { at: env.block.time.seconds() }`

#### Scenario: Expired invitations can still be rejected or revoked
- **WHEN** an invitation's `expires_at` is at or before `env.block.time.seconds()` and either `RejectFamilyInvitation` or `RevokeFamilyInvitation` is sent for it
- **THEN** the call succeeds, the pending entry is removed, and the archive records the appropriate terminal status

### Requirement: Leave and kick remove the membership and archive a past-member record

`ExecuteMsg::LeaveFamily { node_id }` SHALL require the sender to be the controller of `node_id` (failing with `SenderDoesntControlNode` otherwise). `ExecuteMsg::KickFromFamily { node_id }` SHALL require the sender to be the current owner of a family, and the node MUST be a member of *that* family — kicking a node belonging to a different family fails with `NodeNotMemberOfFamily { node_id, family_id }`; kicking a node that has no membership at all fails with `NodeNotInFamily { node_id }`. Both handlers SHALL share the same storage operation: remove `family_members[node_id]`, decrement `NodeFamily::members`, and archive a `PastFamilyMember { family_id, node_id, removed_at: env.block.time.seconds() }` under `((family_id, node_id), counter)` using the next free per-`(family, node)` slot. The respective events are `family_member_left` (carrying the leaver's `family_id` and `node_id`) and `family_member_kicked` (carrying the owner's `family_id` and the kicked `node_id`).

#### Scenario: Node controller leaves the family
- **WHEN** node controller sends `LeaveFamily { node_id }` for a node currently in family `F`
- **THEN** `family_members[node_id]` is removed, `F.members` is decremented, the archive contains a `PastFamilyMember` with `removed_at = env.block.time.seconds()`, and the response carries a `family_member_left` event

#### Scenario: Owner kicks a member of their family
- **WHEN** family owner sends `KickFromFamily { node_id }` for a member of their family
- **THEN** the same storage transition as a leave occurs and the response carries a `family_member_kicked` event

#### Scenario: Owner cannot kick a node belonging to another family
- **WHEN** family owner sends `KickFromFamily { node_id }` for a node whose membership is in a different family `G`
- **THEN** the call fails with `NodeNotMemberOfFamily { node_id, family_id: owned.id }` and storage is unchanged

#### Scenario: Repeated join/leave of the same family uses sequential archive counters
- **WHEN** node `n` joins, leaves, joins again, and leaves again the same family `F`
- **THEN** the archive contains `past_family_members[((F.id, n), 0)]` and `past_family_members[((F.id, n), 1)]` with the respective `removed_at` timestamps

### Requirement: Only the configured mixnet contract may invoke the unbonding callback

`ExecuteMsg::OnNymNodeUnbond { node_id }` SHALL be authorised solely by checking `info.sender == stored mixnet_contract_address`, failing with `UnauthorisedMixnetCallback { sender }` otherwise. There is no node-side or admin override.

#### Scenario: Mixnet contract triggers the callback
- **WHEN** the mixnet contract sends `OnNymNodeUnbond { node_id }`
- **THEN** the call proceeds and the cleanup (see next requirement) is applied

#### Scenario: Arbitrary sender is rejected
- **WHEN** any address other than the stored mixnet contract sends `OnNymNodeUnbond`
- **THEN** the call fails with `UnauthorisedMixnetCallback { sender }`

### Requirement: The unbonding callback is idempotent over membership and sweeps every pending invitation addressed to the node

A successful `OnNymNodeUnbond { node_id }` SHALL:

- if `family_members[node_id]` exists, remove the membership and archive a `PastFamilyMember` exactly as the `leave` / `kick` path does (decrementing the family's `members` count);
- if no such membership exists, leave membership state untouched (this is the common case — most unbonding nodes were never in a family);
- iterate every entry of `pending_family_invitations` keyed by `node_id` (via the `node` multi-index), remove each from the pending map, and archive each as `PastFamilyInvitation { invitation, status: Rejected { at: env.block.time.seconds() } }` using the next free per-`(family, node)` counter;
- emit a `family_node_unbond_cleanup` event with `node_id` attribute.

The auto-cleared invitations share the `Rejected` terminal state with invitations the node controller would have explicitly declined — `Revoked` is reserved for owner-side actions.

**Operational note (non-normative)**: like the disband sweep, the per-node invitation sweep iterates every pending invitation addressed to `node_id` and archives each in a single transaction. Gas cost therefore scales linearly with the number of outstanding invitations the unbonding node holds. If a node has accumulated an unusually large number of pending invitations, the operator-initiated unbond transaction on the mixnet contract may fail because *this* callback exceeds the per-tx gas limit. The fix is operator-side: explicitly `RejectFamilyInvitation` the outstanding invitations (in batches if needed) before retrying the unbond. There is no contract-side chunking, and the mixnet contract has no path to bypass or partial-apply the callback.

#### Scenario: Unbonding node with no family and no pending invitations is a no-op
- **WHEN** `OnNymNodeUnbond { node_id }` is invoked for a node with no membership and no pending invitations
- **THEN** the call succeeds, no storage is changed (apart from emitting the cleanup event), and no error is returned

#### Scenario: Unbonding node in a family loses its membership
- **WHEN** `OnNymNodeUnbond { node_id }` is invoked for a node currently in family `F`
- **THEN** `family_members[node_id]` is removed, `F.members` is decremented, and a `PastFamilyMember` is archived with `removed_at = env.block.time.seconds()`

#### Scenario: Unbonding node's pending invitations are archived as Rejected
- **WHEN** node `n` has pending invitations from families `F1` and `F2` and `OnNymNodeUnbond { node_id: n }` is invoked
- **THEN** both pending entries are removed and `past_family_invitations[((F1.id, n), …)]` and `past_family_invitations[((F2.id, n), …)]` each carry `status = Rejected { at: env.block.time.seconds() }`

### Requirement: Expired pending invitations remain in storage until explicitly cleared

The contract SHALL NOT run any background sweep of expired pending invitations. A `FamilyInvitation` whose `expires_at <= env.block.time.seconds()` SHALL remain in `pending_family_invitations` until either the family owner revokes it, the node controller rejects it, the family owner re-invites the same node (which archives the stale entry as `Expired { at: now }` and replaces it), or the family is disbanded. Accept attempts against such entries MUST fail with `InvitationExpired`. Read queries SHALL surface a boolean `expired` flag (`now >= invitation.expires_at`) on each returned `PendingFamilyInvitationDetails` so callers can filter without doing the comparison themselves.

#### Scenario: Expired invitation is still listed by pending queries
- **WHEN** family `F` has a pending invitation for node `n` whose `expires_at` is in the past and `GetPendingInvitationsForFamilyPaged { family_id: F.id }` is queried
- **THEN** the result includes the entry with `expired = true`

#### Scenario: Expired invitation can be revoked or rejected but not accepted
- **WHEN** an expired invitation exists for `(F.id, n)`
- **THEN** `AcceptFamilyInvitation` fails with `InvitationExpired`, but `RevokeFamilyInvitation` (by `F`'s owner) and `RejectFamilyInvitation` (by `n`'s controller) both succeed and archive the invitation with the corresponding terminal status

### Requirement: Per-`(family, node)` archive slots use sequential counters starting at 0

Both `past_family_invitations` and `past_family_members` SHALL be keyed by `((family_id, node_id), counter: u64)`. The contract SHALL maintain explicit per-`(family, node)` counter maps (`past_family_invitation_counter`, `past_family_member_counter`), starting at `0` for each new pair and incrementing by `1` on each archival write. Counters MUST be independent across distinct `(family, node)` pairs and across the two archive types.

#### Scenario: First archive slot for a new pair is 0
- **WHEN** a node and family appear in either archive for the first time
- **THEN** the entry is keyed with `counter = 0`

#### Scenario: Distinct pairs have independent counters
- **WHEN** archive entries are written under keys `(F1, n)` and `(F2, n)` in any order
- **THEN** each pair's counter starts independently at `0`

### Requirement: GetFamilyMembership returns the family id a node belongs to, or None

`QueryMsg::GetFamilyMembership { node_id }` SHALL return `NodeFamilyMembershipResponse { node_id, family_id }` where `family_id` is `Some(NodeFamilyId)` iff `family_members[node_id]` is populated, and `None` otherwise. The query MUST NOT fail when `node_id` is unknown — it returns `family_id: None`. The query is the canonical way for route-selection consumers to check whether two node ids belong to the same family without scanning members.

#### Scenario: Member node returns its family id
- **WHEN** node `n` is currently a member of family `F` and `GetFamilyMembership { node_id: n }` is queried
- **THEN** the response carries `family_id = Some(F.id)`

#### Scenario: Non-member node returns None
- **WHEN** `GetFamilyMembership { node_id }` is queried for a node that has no membership record (never joined, or has since left/been kicked/unbonded)
- **THEN** the response carries `family_id = None` and `node_id` echoed back

### Requirement: Single-family-by-id, by-name, and by-owner queries return an `Option<NodeFamily>`

The contract SHALL expose three single-family lookups via `QueryMsg::GetFamilyById`, `GetFamilyByName`, and `GetFamilyByOwner`, each returning a response that echoes the queried key back to the caller for correlation and a `family: Option<NodeFamily>` field that is `None` when no match exists. `GetFamilyByName` MUST normalise the input via the same `normalise_family_name` function the create path uses before consulting the unique index. `GetFamilyByOwner` MUST bech32-validate the input.

#### Scenario: GetFamilyByName is invariant under input formatting
- **WHEN** family `F` exists with `name = "MyFamily"` and `GetFamilyByName { name: "my family" }` is queried
- **THEN** the response carries `family = Some(F)` (the lookup hits the unique normalised-name index)

#### Scenario: Missing match returns None
- **WHEN** any of the three single-family queries is called with a key that matches no family
- **THEN** the response carries `family = None` and echoes the queried key

#### Scenario: GetFamilyByOwner rejects an invalid bech32 address
- **WHEN** `GetFamilyByOwner { owner }` is called with a non-bech32 string
- **THEN** the call returns an error sourced from `Addr::validate`

### Requirement: Paginated queries use exclusive `start_after`, default limit 50, max limit 100

Every paginated query (`GetFamiliesPaged`, `GetFamilyMembersPaged`, `GetAllFamilyMembersPaged`, `GetPendingInvitationsForFamilyPaged`, `GetPendingInvitationsForNodePaged`, `GetAllPendingInvitationsPaged`, `GetPastInvitationsForFamilyPaged`, `GetPastInvitationsForNodePaged`, `GetAllPastInvitationsPaged`, `GetPastMembersForFamilyPaged`, `GetPastMembersForNodePaged`) SHALL accept `start_after: Option<Cursor>` (exclusive) and `limit: Option<u32>`. The default `limit` SHALL be `50` and SHALL be clamped to `100` as a hard cap. Results SHALL be in ascending cursor order. Each response SHALL include a `start_next_after: Option<Cursor>` derived from the last entry of the page, with `None` indicating the page is empty (the caller treats this as end-of-list).

Per-family / per-node paginated queries SHALL NOT verify that the supplied `family_id` or `node_id` corresponds to an existing entity — an unknown id simply yields an empty page.

#### Scenario: Limit is defaulted and clamped
- **WHEN** any paginated query is called with `limit = None`
- **THEN** at most 50 entries are returned
- **AND** when called with `limit = Some(10_000)` at most 100 entries are returned

#### Scenario: Empty page signals end-of-list
- **WHEN** a paginated query has no more entries past the supplied `start_after`
- **THEN** the response carries an empty entry list and `start_next_after = None`

#### Scenario: Unknown scope id yields an empty page rather than an error
- **WHEN** `GetFamilyMembersPaged { family_id: 999_999, .. }` is queried for a non-existent family id
- **THEN** the response carries an empty `members` list and `start_next_after = None` (no error is returned)

### Requirement: Pending-invitation queries stamp each entry with its expiry flag

Queries returning pending invitations (`GetPendingInvitation`, `GetPendingInvitationsForFamilyPaged`, `GetPendingInvitationsForNodePaged`, `GetAllPendingInvitationsPaged`) SHALL wrap each invitation in `PendingFamilyInvitationDetails { invitation, expired }` where `expired = env.block.time.seconds() >= invitation.expires_at`. Past-invitation and past-member queries do not carry this flag (they are terminal-state archives).

#### Scenario: Future-dated invitation is marked not expired
- **WHEN** a pending invitation has `expires_at = env.block.time.seconds() + 60` and any pending-invitation query returns it
- **THEN** the returned `PendingFamilyInvitationDetails.expired` is `false`

#### Scenario: Past-dated invitation is marked expired
- **WHEN** a pending invitation has `expires_at = env.block.time.seconds() - 1`
- **THEN** any pending-invitation query that returns it sets `expired = true`

### Requirement: Storage-key constants are part of the public contract

Every constant exported under `nym_node_families_contract_common::constants::storage_keys` SHALL be treated as part of the public contract surface. Off-chain indexers and migration tooling may depend on these exact byte strings. Changing the value of any existing constant — including renaming a namespace — SHALL be considered a breaking change for already-deployed contracts and SHALL be accompanied by a data migration via `queued_migrations`. Adding new constants for new storage maps is non-breaking. The current set covers the contract-level items (admin, config, mixnet contract address, family id counter), the primary maps (`families`, `node-family-members`, `invitations`, `past-invitations`, `past-family-member`), every secondary index (`__owner`, `__name`, `__family`, `__node`), and the per-`(family, node)` archive counters — refer to `constants.rs` for the authoritative list.

#### Scenario: Storage key constants are reachable from the common crate
- **WHEN** an off-chain consumer imports `nym_node_families_contract_common::constants::storage_keys`
- **THEN** it observes the full set of storage-key constants the contract uses, without taking a dependency on the contract crate itself

### Requirement: Emitted events form a stable public surface

Every event name and attribute key exported under `nym_node_families_contract_common::constants::events` SHALL be treated as part of the public contract surface. Each successful **state-mutating user-facing execute path** (every variant of `ExecuteMsg` except `UpdateConfig`, which is an admin handler that returns `Response::default()` without an event, and the no-op `UpdateFamily { updated_name: None, updated_description: None }` short-circuit, which also returns `Response::default()` because nothing changed) SHALL emit exactly one event whose name and attribute keys come from these constants. Renaming an event name constant, renaming an attribute-key constant, or changing the set of attributes a given event always carries SHALL be treated as breaking changes. Adding new constants for new events / attributes is non-breaking, as is making a previously-always-emitted attribute conditional only by extending the variant set that triggers it (see `family_update` below).

At the time of this spec the constant surface comprises (refer to `constants.rs` for the authoritative list):

- `family_creation` — attributes: `family_name`, `owner_address`, `family_id`, `paid_fee`
- `family_update` — required attributes: `family_id`, `owner_address`. Conditional attributes: `updated_name` (emitted only when the call carried `updated_name = Some(_)`), `updated_description` (emitted only when the call carried `updated_description = Some(_)`). At least one of the two conditional attributes is always present, because the no-op no-name-no-description case short-circuits to `Response::default()` without emitting any event at all.
- `family_disband` — attributes: `family_id`, `owner_address`, `refunded_fee`
- `family_invitation` — attributes: `family_id`, `node_id`, `expires_at`
- `family_invitation_revoked` — attributes: `family_id`, `node_id`
- `family_invitation_accepted` — attributes: `family_id`, `node_id`
- `family_invitation_rejected` — attributes: `family_id`, `node_id`
- `family_member_left` — attributes: `family_id`, `node_id`
- `family_member_kicked` — attributes: `family_id`, `node_id`
- `family_node_unbond_cleanup` — attributes: `node_id`

**Note for indexer authors (non-normative)**: CosmWasm wraps user-emitted events in a `wasm-` prefix when they land in the tendermint event log. So `family_creation` appears as `wasm-family_creation` on the chain side, `family_invitation` as `wasm-family_invitation`, etc. The constants in `constants::events` are the *unprefixed* names — indexers querying the chain need to add the `wasm-` prefix themselves (or use the prefix-stripping helpers most Cosmos indexer SDKs already provide).

#### Scenario: Each successful state-mutating execute path emits exactly its named event
- **WHEN** any of the execute paths listed above succeeds (i.e. every `ExecuteMsg` variant other than `UpdateConfig`)
- **THEN** the response carries exactly one event whose `ty` equals the corresponding constant from `constants::events` and whose attributes include each of the listed keys

#### Scenario: UpdateConfig is the exception — no event is emitted
- **WHEN** the admin sends `ExecuteMsg::UpdateConfig` and the call succeeds
- **THEN** the response is `Response::default()` and carries no event (this is intentional — `UpdateConfig` is administrative metadata, not a tracked state transition)

#### Scenario: No-op UpdateFamily is the second exception — no event is emitted
- **WHEN** any sender sends `ExecuteMsg::UpdateFamily { updated_name: None, updated_description: None }` and the call succeeds (the no-op short-circuit)
- **THEN** the response is `Response::default()` and carries no event — because nothing in storage changed, there is nothing for indexers to observe