Comprehensive Design Document Namespaces - reddcoin-project/reddcoin GitHub Wiki
Version 1.0 | March 2025
This document presents a comprehensive design for implementing a Namespace Auction System for Reddcoin. The system establishes a two-tiered market approach where top-level namespaces are auctioned first, and those namespace owners then define the rules for user IDs within their namespace.
The namespace auction system creates a market-driven framework that:
- Properly values premium namespace identifiers through competitive bidding
- Allows customization of rules and economic parameters for each namespace
- Creates a sustainable economic model with multi-level revenue generation
- Establishes governance structures for long-term namespace management
- Reduces squatting and speculation through significant investment requirements
Namespace owners gain the right to customize rules for their namespace and receive a share of user ID auction revenues, incentivizing them to build value and utility within their namespace.
- Core System Architecture
- Namespace Auction Mechanics
- Namespace Configuration Parameters
- Blockchain Integration
- P2P Protocol Extensions
- Database Schema
- Economic Model
- User Interface Design
- Implementation Plan
- Integration with User ID Auctions
- Governance Framework
- Appendices
The Namespace Auction System extends the Reddcoin Core protocol to facilitate the registration, transfer, and renewal of top-level namespaces through competitive bidding.
The system consists of the following core components:
-
Namespace Auction Manager: Central component handling namespace auction creation, bid processing, and auction finalization
-
Namespace Configuration Manager: Responsible for storing, validating, and distributing namespace configuration parameters
-
Storage Layer: Database structures for persistent storage of namespace auction and configuration data
-
Blockchain Interface: Mechanisms for writing namespace auction data to the Reddcoin blockchain via OP_RETURN outputs
-
P2P Relay Network: Extension of the Reddcoin P2P protocol to efficiently propagate namespace-related messages
-
User Interface: Wallet integration providing namespace auction browsing, bidding, and configuration
-
Namespace Creation:
- User requests to create a namespace auction
- System validates namespace ID availability and format
- User defines namespace configuration parameters
- Auction is recorded on blockchain and propagated via P2P network
-
Bidding Process:
- Users view available namespace auctions and place bids
- Bids are validated against auction requirements
- Valid bids are recorded on blockchain and propagated
- Previous high bidders are notified about being outbid
-
Auction Finalization:
- System detects auction end based on time parameters
- Highest valid bid is determined as winner
- Namespace registration is processed for the winner
- Configuration parameters are stored and distributed via P2P
-
Namespace Management:
- Namespace owner can update certain configuration parameters
- Updates are validated and propagated through the network
- Periodic renewal of namespace ownership is required
For a valid namespace auction:
-
Namespace ID Format:
- Length: 1-15 characters
- Allowed characters: lowercase letters (a-z), numbers (0-9), hyphen (-)
- Cannot begin or end with a hyphen
- Must be unique across the system
-
Auction Duration:
- Minimum: 14 days
- Maximum: 30 days
- Default: 14 days
-
Deposit Requirements:
- 20% of bid amount must be deposited
- Higher percentage than user ID auctions to ensure serious participation
-
Reserve Prices:
- Minimum: 10,000 RDD
- Single character: 100,000 RDD minimum
- Two characters: 50,000 RDD minimum
- Three characters: 25,000 RDD minimum
- Four+ characters: 10,000 RDD minimum
The namespace auction follows this defined state flow:
[Initial State] → [Namespace Auction Creation] → [Namespace Auction Open] → [Auction Ended] → [Namespace Active]
Detailed state flow is visualized in the namespace auction flow diagram referenced in the appendices.
- Minimum Increment: New bids must exceed the current highest bid by at least 5%
- Deposit Requirement: Bidders must include a 20% deposit of their bid amount
- Anti-Sniping: Auctions extend by 12 hours if a bid is placed in the final 24 hours
- Maximum Extensions: Limited to 5 extensions to ensure eventual completion
- Validation: Bids must include proof of funds and be cryptographically signed
- Once auction time elapses, the auction enters the finalization phase
- The highest valid bid is identified as the winner
- The winner's full bid amount is processed according to the revenue distribution model
- Deposits from losing bidders are refunded (minus processing fees)
- The namespace is registered to the winner's address
- Configuration parameters are stored and distributed to the network
Namespace owners can configure multiple parameters that govern how user IDs within their namespace operate:
-
Allowed Characters:
- Letters (a-z) are always allowed
- Numbers (0-9) can be toggled on/off
- Hyphens (-) can be toggled on/off
- Underscores (_) can be toggled on/off
-
Length Requirements:
- Minimum length: 1-10 characters (configurable)
- Maximum length: 5-64 characters (configurable)
- Default: 3-32 characters
-
Revenue Distribution:
- Namespace Owner: 5-10% (configurable within platform limits)
- Burn Rate: 50-80% (configurable with minimum 50%)
- Node Operators: 5-25% (configurable)
- Development Fund: 5-15% (configurable)
- Total must equal 100%
-
Pricing Tiers:
- Custom minimum prices based on name length
- Can be adjusted to prioritize certain length ranges
- Platform enforces minimum values for each tier
-
Usage Incentives:
- Discount multipliers for active usage
- Penalty multipliers for inactive names
- Custom bulk ownership penalties
-
User ID Auction Duration:
- Minimum duration: 1-7 days (configurable)
- Maximum duration: 3-14 days (configurable)
- Default: 3-7 days
-
Bidding Rules:
- Minimum bid increment: 1-10% (configurable)
- Deposit requirement: 5-20% (configurable)
- Anti-sniping extension period: 1-24 hours (configurable)
-
Renewal Period:
- Duration before renewal required: 180-730 days (configurable)
- Default: 365 days
-
Grace Period:
- Duration after expiration before auction: 14-60 days (configurable)
- Default: 30 days
-
Renewal Fees:
- Base percentage of equivalent auction price: 25-75% (configurable)
- Default: 50%
The system uses Reddcoin's OP_RETURN capability to record namespace auction data on-chain, with specialized formats for different namespace operations:
0 2 3 7 8 16 17 25 26 34 35 39 74
|-----|--|----------|----|---------|----|-----|-----|------|---------|----|----------|
magic op auctionId type nameHash ns start end reserve depositPct configHash
The full configuration is too large for OP_RETURN, so only a hash is included. The complete configuration is transmitted via P2P.
0 2 3 7 8 16 17 25
|-----|--|----------|----|---------|----|-----|
magic op auctionId hash bidAmount time
0 2 3 7 8 16 17 25
|-----|--|----------|----|---------|----|-----|
magic op auctionId hash winAmount time
0 2 3 7 8 16
|-----|--|----------|----|---------|
magic op auctionId hash time
The system defines the following new operation codes:
Code | Symbol | Description |
---|---|---|
OP_NAMESPACE_AUCTION_CREATE |
{ |
Create a new namespace auction |
OP_NAMESPACE_AUCTION_BID |
} |
Submit bid for a namespace |
OP_NAMESPACE_AUCTION_FINALIZE |
[ |
Finalize namespace auction to winner |
OP_NAMESPACE_AUCTION_CANCEL |
] |
Cancel a namespace auction (by creator only) |
New consensus rules are implemented to enforce:
- Validity of namespace operations
- Correct sequence of state transitions
- Appropriate fee payments
- Authorization of operations
- Namespace configuration parameter boundaries
The P2P protocol is extended with additional message types for namespace operations:
Message Type | Value | Description |
---|---|---|
MSG_NAMESPACE_AUCTION_ANNOUNCE |
0x11 |
Announce a new namespace auction |
MSG_NAMESPACE_AUCTION_BID |
0x12 |
Announce a bid on a namespace |
MSG_NAMESPACE_AUCTION_FINALIZE |
0x13 |
Announce namespace finalization |
MSG_NAMESPACE_AUCTION_CANCEL |
0x14 |
Announce namespace cancellation |
MSG_NAMESPACE_CONFIG_REQUEST |
0x15 |
Request namespace configuration |
MSG_NAMESPACE_CONFIG_RESPONSE |
0x16 |
Provide namespace configuration |
Since the full namespace configuration is too large for OP_RETURN, it's distributed through the P2P network:
- When a namespace auction is finalized, the winner's configuration is stored in the local database.
- A configuration hash is included in the blockchain transaction.
- Nodes can request the full configuration by sending a
MSG_NAMESPACE_CONFIG_REQUEST
message. - Nodes with the configuration respond with a
MSG_NAMESPACE_CONFIG_RESPONSE
message. - Receiving nodes validate the configuration against the hash from the blockchain.
Nodes can subscribe to namespace events:
- Filter by specific namespaces of interest
- Receive notifications about auctions, bids, and configuration changes
- Prioritize relay of namespace messages to interested nodes
Stores information about all namespace auctions.
Column | Type | Description |
---|---|---|
auction_id |
BLOB(32) | Unique identifier for the auction (uint256) |
namespace_id |
VARCHAR(15) | Namespace being auctioned |
creator_address |
BLOB | Creator's address in binary format |
start_time |
INT64 | Start time (unix timestamp) |
end_time |
INT64 | End time (unix timestamp) |
reserve_price |
INT64 | Minimum acceptable bid |
current_bid |
INT64 | Highest current bid amount |
current_bidder |
BLOB | Address of highest bidder |
deposit_amount |
INT64 | Required deposit amount |
state |
INT | Current auction state (0=pending, 1=active, 2=ended, 3=finalized, 4=cancelled) |
config_hash |
BLOB(32) | Hash of configuration |
config |
BLOB | Serialized configuration data |
block_height |
INT | Block height when auction was created |
txid |
BLOB(32) | Transaction ID of the auction creation transaction |
Stores information about bids on namespace auctions.
Column | Type | Description |
---|---|---|
bid_id |
BLOB(32) | Unique identifier for the bid |
auction_id |
BLOB(32) | Reference to the auction |
bidder_address |
BLOB | Bidder's address in binary format |
bid_amount |
INT64 | Bid amount |
deposit_amount |
INT64 | Deposit amount paid |
bid_time |
INT64 | Time when bid was placed |
txid |
BLOB(32) | Transaction ID of the bid transaction |
is_winner |
BOOLEAN | Whether this bid won the auction |
refunded |
BOOLEAN | Whether the deposit was refunded |
Stores the active configuration for each namespace.
Column | Type | Description |
---|---|---|
namespace_id |
VARCHAR(15) | Namespace identifier (PK) |
owner_address |
BLOB | Owner's address |
allow_numbers |
BOOLEAN | Whether numbers are allowed |
allow_hyphens |
BOOLEAN | Whether hyphens are allowed |
allow_underscores |
BOOLEAN | Whether underscores are allowed |
min_length |
INT | Minimum name length |
max_length |
INT | Maximum name length |
renewal_period |
INT | Days until renewal required |
grace_period |
INT | Days in grace period |
namespace_revenue_pct |
INT | % of auctions going to namespace owner |
burn_pct |
INT | % of auctions being burned |
node_pct |
INT | % of auctions going to node operators |
dev_pct |
INT | % of auctions going to development fund |
min_auction_duration |
INT | Minimum auction duration in days |
max_auction_duration |
INT | Maximum auction duration in days |
min_bid_increment |
REAL | Minimum bid increment percentage |
config_hash |
BLOB(32) | Hash of this configuration |
last_updated |
INT64 | When configuration was last updated |
expiration |
INT64 | When namespace ownership expires |
Stores pricing tiers for different name lengths within a namespace.
Column | Type | Description |
---|---|---|
namespace_id |
VARCHAR(15) | Namespace identifier (PK, FK) |
min_length |
INT | Minimum length for this tier (PK) |
min_price |
INT64 | Minimum price for names in this tier |
Stores usage-based discount tiers for a namespace.
Column | Type | Description |
---|---|---|
namespace_id |
VARCHAR(15) | Namespace identifier (PK, FK) |
min_usage |
INT | Minimum usage level (transactions per month) (PK) |
discount_multiplier |
REAL | Fee multiplier (1.0=standard, 0.5=50% discount) |
Stores bulk ownership penalty tiers for a namespace.
Column | Type | Description |
---|---|---|
namespace_id |
VARCHAR(15) | Namespace identifier (PK, FK) |
max_owned |
INT | Maximum number of names owned for this tier (PK) |
penalty_multiplier |
REAL | Fee multiplier (1.0=standard, 2.0=100% premium) |
Namespace values are determined by several factors:
- Length and Readability: Shorter, more readable namespaces command higher prices
- Common Words: Dictionary words and common terms have higher value
- Specialized Markets: Namespaces targeting popular sectors (finance, gaming) have premium value
- Market Competition: Auction process ensures price discovery
The namespace auction system includes a flexible revenue distribution model:
-
Platform-Level Controls:
- Minimum burn rate: 50% of all namespace auction proceeds
- Maximum namespace owner share: 10% of user ID auction proceeds
- Minimum node operator share: 5% of proceeds
- Minimum development fund: 5% of proceeds
-
Namespace-Level Configuration:
- Namespace owners configure exact percentages within platform limits
- Typical configuration: 70% burn, 10% namespace owner, 15% nodes, 5% development
-
Implementation Mechanisms:
- Burn: Tokens sent to provably unspendable addresses
- Namespace owner: Direct payment to owner's wallet
- Node operators: Distribution to active full nodes
- Development fund: Multi-signature wallet
Namespace ownership requires periodic renewal:
- Renewal Period: Typically 365 days (configurable 180-730 days)
-
Renewal Fee: Based on several factors:
- Base fee: 25% of equivalent auction price
- Usage multiplier: Based on number of active IDs in namespace
- Activity multiplier: Based on transaction volume in namespace
- Grace Period: 30 days (configurable 14-60 days)
- Reclamation Auction: If not renewed, enters public auction with no priority for previous owner
The namespace system creates aligned incentives:
-
Namespace Owners: Motivated to increase value through:
- Promoting their namespace to users
- Setting fair and competitive pricing
- Creating useful services around their namespace
- Maintaining reasonable rules
-
Users: Benefit from stable namespace governance:
- Clear rules established by namespace
- Competitive pricing for IDs
- Value-added services
-
Network: Benefits from:
- Increased transaction volume
- Deflationary token burning
- Development funding
- Node operator incentives
The namespace auction browser provides a view of available namespaces:
Key features include:
- Filtering by namespace status and characteristics
- Search functionality for specific namespaces
- Detail view showing configuration and auction status
- One-click access to bidding interface
The configuration interface allows namespace creators to define parameters:
Key sections include:
- Basic Information: Namespace ID, reserve price, duration
- Character Rules: Allowed characters, length requirements
- Economic Parameters: Revenue distribution, pricing tiers
- Auction Parameters: Duration, bid increments, deposits
The dashboard provides namespace owners with management tools:
Key features include:
- Performance metrics for the namespace
- User ID statistics and trends
- Configuration update interface
- Renewal management
Phase | Timeline | Focus |
---|---|---|
Design & Planning | Weeks 1-4 | Specification finalization, documentation |
Core Development | Weeks 5-16 | Core namespace functionality, blockchain integration |
UI/UX Development | Weeks 12-20 | Configuration interface, auction browser |
Testing & QA | Weeks 16-24 | Testing, security audits, beta program |
Deployment & Launch | Weeks 25-28 | Mainnet deployment, monitoring |
-
Core Protocol Extensions:
- Define namespace auction OP_RETURN formats
- Implement namespace validation rules
- Create consensus rules for namespace operations
-
Database Development:
- Implement namespace auction tables
- Create configuration storage schema
- Develop synchronization mechanisms
-
P2P Protocol Extensions:
- Implement namespace message types
- Create configuration distribution system
- Develop subscription mechanisms
-
Economic System Implementation:
- Implement revenue distribution logic
- Create renewal fee calculation
- Develop namespace valuation algorithms
-
User Interface Development:
- Create namespace auction browser
- Build configuration interface
- Develop namespace management dashboard
Risk | Impact | Likelihood | Mitigation |
---|---|---|---|
Initial namespace land grab | High | High | Controlled rollout, reserved namespaces, high minimum prices |
Configuration exploitation | High | Medium | Platform-level limits, parameter validation, governance controls |
Low participation | Medium | Medium | Initial reserved auctions, targeted marketing, showcase namespaces |
Abandoned namespaces | Medium | Medium | Mandatory renewal, reclamation auctions, activity requirements |
Trademark disputes | High | Low | Dispute resolution mechanism, name reservation for known brands |
The namespace auction system integrates directly with the user ID auction system:
- Namespace First: Namespaces must be registered before any user IDs within them
- Rule Inheritance: User ID auctions inherit rules from their parent namespace
- Configuration Propagation: Namespace configuration changes affect all future user ID auctions
- Revenue Flow: User ID auction proceeds flow partially to namespace owners
-
Validation Chain:
- User ID requests are validated against namespace rules
- Character set restrictions are enforced
- Length requirements are verified
- Pricing follows namespace-defined tiers
-
Auction Management:
- Namespace-defined auction parameters control user ID auctions
- Duration, bid increments, and extension rules follow namespace settings
- Deposit requirements align with namespace configuration
-
Revenue Distribution:
- User ID auction proceeds are split according to namespace configuration
- Namespace owner receives their defined percentage
- Remaining funds distributed to burn, nodes, and development
The integrated user experience includes:
- Namespace-Specific Browsing: Users can browse user IDs within a specific namespace
- Clear Rule Presentation: Each namespace displays its rules prominently
- Unified Management: Users can manage both namespaces and user IDs in a single interface
- Streamlined Renewal: Coordinated renewal notifications for both levels
The Reddcoin platform maintains governance over:
- Parameter Boundaries: Minimum/maximum values for namespace configuration
- Reserved Namespaces: Initial set of reserved namespaces for official use
- Protocol Rules: Consensus-level rules for namespace operations
- Dispute Resolution: Process for handling namespace ownership disputes
Namespace owners have governance rights over:
- Configuration Updates: Ability to update certain parameters
- User ID Rules: Setting character and length requirements
- Economic Parameters: Adjusting pricing tiers and revenue distribution
- Auction Parameters: Modifying auction duration and bid requirements
To prevent abuse, namespace governance has limitations:
- Parameter Boundaries: All parameters must stay within platform-defined limits
- Update Frequency: Some parameters can only be changed after minimum periods
- Grandfather Clauses: Existing user IDs are protected from rule changes
- Revocation Conditions: Conditions under which namespace ownership can be revoked
A framework for handling disputes includes:
- Trademark Claims: Process for trademark holders to claim relevant namespaces
- Abuse Reports: Mechanism for reporting abusive namespace usage
- Arbitration Process: Multi-stakeholder process for resolving disputes
- Appeals Procedure: Method to challenge governance decisions
- Namespace System Architecture Diagram
- Namespace Auction Flow Diagram
- Namespace Database Entity Relationship Diagram
- P2P Protocol Message Flow