sigil-core · username

pub const USERNAME_MAX_LEN: usize;

pub const USERNAME_MIN_LEN: usize;

pub const RESERVED_GENESIS_USERNAMES: &[&str];

pub const USERNAME_MAX_LEASE_YEARS: u32;

pub const DEFAULT_PRICE_3_CHAR: u128;

pub const DEFAULT_PRICE_4_CHAR: u128;

pub const DEFAULT_PRICE_5_CHAR: u128;

pub const DEFAULT_PRICE_6_PLUS_CHAR: u128;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct UsernameRecord {
/// Canonical (lowercased, ASCII-validated) username.

pub name: String,
/// DID of the current owner.

pub owner_did: String,
/// Block height at registration.

pub registered_at_height: u64,
/// Block height at which the lease expires.

pub expires_at_height: u64,
/// Optional content hash of off-chain metadata (avatar, profile).

pub metadata_cid: Option<SigilHash>,
/// Set if this name is in the genesis-pinned reserved list.

pub is_reserved: bool,
/// Set while a `RaiseUsernameDispute` is pending resolution.

pub is_disputed: bool
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ReverseUsernameRecord {
pub did: String,
pub primary: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct UsernameParams {
/// Whether the username feature is enabled at genesis.

pub enabled: bool,
/// Approximate blocks per year (used for lease term computation).

pub blocks_per_year: u64,
/// Per-length-tier annual lease price in base units.

pub price_3_char: u128,
pub price_4_char: u128,
pub price_5_char: u128,
pub price_6_plus_char: u128,
/// Global price multiplier in basis points (10000 = 1.0x).

/// Governance-adjustable with a 90-day timelock.

pub price_multiplier_bps: u32,
/// Maximum lease duration in years.

pub max_lease_years: u32,
/// Reserved list (cannot be registered without governance).

pub reserved: Vec<String>,
/// DID of the dispute-resolver multisig.

pub dispute_multisig_did: String,
/// DID of the appellate dispute multisig.

pub appeal_multisig_did: String,
/// Filing fee for raising a dispute (in base units).

pub dispute_filing_fee: u128,
/// Filing fee for appealing a dispute (in base units).

pub dispute_appeal_fee: u128,
/// Members of the primary dispute multisig (DID + Ed25519 pubkey).

/// Empty list disables dispute resolution (fail-closed).

#[serde(default)]
pub dispute_multisig_signers: Vec<DisputeSignerEntry>,
/// Number of valid signatures required to resolve a dispute.

/// `dispute_multisig_signers.len() >= dispute_multisig_threshold` MUST

/// hold for genesis to be valid.

#[serde(default)]
pub dispute_multisig_threshold: u32
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DisputeSignerEntry {
pub signer_did: String,
/// 32-byte Ed25519 public key, hex-encoded (no `0x` prefix).

pub public_key_hex: String
}

pub fn validate_username(input: &str) -> Result<String, CoreError>;

pub fn validate_genesis_username(input: &str) -> Result<String, CoreError>;

pub fn compute_lease_price(
    canonical_name: &str,
    years: u32,
    params: &UsernameParams,
) -> Result<u128, CoreError>;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RegisterUsernameData {
/// Username (will be canonicalized at executor time).

pub name: String,
/// DID of the new owner.

pub owner_did: String,
/// Number of years to prepay (1..=`max_lease_years`).

pub years: u32,
/// Optional metadata content hash to set at registration.

pub metadata_cid: Option<SigilHash>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TransferUsernameData {
pub name: String,
pub new_owner_did: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ReleaseUsernameData {
pub name: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SetUsernameMetadataData {
pub name: String,
pub metadata_cid: Option<SigilHash>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SetReverseUsernameData {
pub did: String,
pub primary: String
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum AuctionStatus {
    /// Bidding is still open. The auction will close after
    /// `auction_anti_snipe_blocks` of silence past `closes_at_height`.
    Open,
    /// A winner has been determined; escrow has been settled and the
    /// username has been registered to the winning bidder.
    Settled,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct UsernameAuction {
/// Canonical name being auctioned (lower-cased ASCII).

pub name: String,
/// Block at which bidding opened.

pub opened_at_height: u64,
/// Earliest block at which the auction may finalize. Pushed forward by

/// `auction_anti_snipe_blocks` whenever a new bid lands within the

/// anti-snipe window.

pub closes_at_height: u64,
/// Current high bid in base units (None if no bid yet).

pub current_bid: Option<u128>,
/// DID of the current high bidder (None if no bid yet).

pub current_bidder: Option<String>,
/// Total number of bids received. Used for the per-DID anti-collusion

/// cap and for explorer display.

pub bid_count: u64,
/// Status (`Open` or `Settled`).

pub status: AuctionStatus
}

pub fn open(name: String, opened_at_height: u64, closes_at_height: u64) -> Self;

pub fn finalizable_at(&self, current_height: u64) -> bool;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct UsernameAuctionBidData {
/// Username being bid on (canonical lowercase).

pub name: String,
/// Bidder DID.

pub bidder_did: String,
/// Bid amount in base units (must be ≥ `current_bid + min_increment`,

/// or ≥ opening price if no current bid).

pub bid_amount: u128
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct UsernameAuctionFinalizeData {
pub name: String
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum DisputeStatus {
    /// A dispute has been filed; the username is locked from transfer.
    Filed,
    /// The multisig has resolved the dispute; outcome was applied.
    Resolved,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum DisputeOutcome {
    /// Transfer the username to `claimant_did` (e.g. legitimate trademark
    /// holder). The original lease is retained; only the owner DID rotates.
    TransferTo { claimant_did: String },
    /// The current owner keeps the name; claimant's filing fee is forfeited
    /// to the treasury.
    RetainCurrent,
    /// The username is released and goes into a 1-year cooldown before it
    /// can be re-registered.
    Forfeit,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct UsernameDispute {
/// Unique dispute ID. Composed by the executor as

/// `BLAKE3(name || claimant_did || filed_at_height)` truncated to 16

/// bytes (hex-encoded). Provides a deterministic, collision-resistant

/// reference for cross-tx state lookup.

pub dispute_id: String,
/// Username being disputed (canonical lower-cased).

pub name: String,
/// DID of the party that filed the dispute (the claimant).

pub claimant_did: String,
/// DID of the username's owner at filing time.

pub respondent_did: String,
/// Block height at which the dispute was filed.

pub filed_at_height: u64,
/// Optional content hash of off-chain evidence (filing brief, screenshots,

/// trademark certificate, etc.).

pub evidence_cid: Option<crate::hash::SigilHash>,
/// Filing fee paid by the claimant, escrowed pending resolution.

pub filing_fee: u64,
/// Current status (`Filed` or `Resolved`).

pub status: DisputeStatus,
/// Resolution outcome (set when `status == Resolved`).

pub outcome: Option<DisputeOutcome>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RaiseUsernameDisputeData {
/// Username being disputed (canonical lower-case).

pub name: String,
/// DID of the claimant (the party filing the dispute). Must equal the

/// transaction sender DID.

pub claimant_did: String,
/// Optional content hash of the off-chain evidence package.

pub evidence_cid: Option<crate::hash::SigilHash>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DisputeMultisigSignature {
/// DID of the signing multisig member.

pub signer_did: String,
/// Ed25519 public key of the signer (32 bytes, hex).

pub public_key_hex: String,
/// Ed25519 signature over the resolution payload (64 bytes, hex).

pub signature_hex: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResolveUsernameDisputeData {
pub dispute_id: String,
pub name: String,
pub outcome: DisputeOutcome,
/// Multisig signatures over the canonical resolution payload.

pub signatures: Vec<DisputeMultisigSignature>
}

pub fn dispute_resolve_signing_bytes(dispute_id: &str, outcome: &DisputeOutcome) -> Vec<u8>;

pub fn compute_dispute_id(name: &str, claimant_did: &str, filed_at_height: u64) -> String;

pub fn compute_auction_opening_price(
    canonical_name: &str,
    params: &UsernameParams,
    auction_initial_bid_multiplier: u32,
) -> Result<u128, CoreError>;

pub fn compute_min_next_bid(
    current_bid: Option<u128>,
    opening_price: u128,
    min_increment_bps: u32,
) -> u128;