Skip to main content

preRegistrationUsername

Centralized Verification

This function uses Core.sol's validateAndConsumeNonce() for signature verification. All NameService operations use async execution (isAsyncExec = true).

Function Type: external
Function Signature: preRegistrationUsername(address,bytes32,address,address,uint256,bytes,uint256,uint256,bytes)

Pre-registers a username hash to prevent front-running attacks during the registration process. This function creates a 30-minute reservation window using a commit-reveal scheme where users commit to a hash of their desired username plus a secret lock number.

Parameters​

ParameterTypeDescription
useraddressThe address of the end-user initiating the pre-registration.
hashPreRegisteredUsernamebytes32The commitment hash calculated as keccak256(abi.encodePacked(username, lockNumber)).
senderExecutoraddressService address authorized to execute (msg.sender). Use address(0) for flexible execution - any service can execute and consume the nonce. Use specific address to restrict to that service only.
originExecutoraddressOptional tx.origin restriction (use address(0) for unrestricted execution).
nonceuint256User's centralized nonce from Core.sol for this operation.
signaturebytesEIP-191 signature authorizing this operation (verified by Core.sol).
priorityFeeEvvmuint256Optional fee (in Principal Tokens) paid to msg.sender (executor) if they are a staker.
nonceEvvmuint256Required if priorityFeeEvvm > 0. User's Core nonce for the payment operation.
signatureEvvmbytesRequired if priorityFeeEvvm > 0. User's signature authorizing the Core payment.
Signature Requirements

NameService Signature (signature):

  • Format: {evvmId},{senderExecutor},{hashPayload},{originExecutor},{nonce},{isAsyncExec}
  • Uses NameServiceHashUtils.hashDataForPreRegistrationUsername(hashPreRegisteredUsername)
  • senderExecutor: Set to address(0) for flexible execution or specific service address for restriction
  • originExecutor: Set to address(0) for no restriction or specific address for tx.origin validation
  • Reference: Pre-Registration Signature Structure

Payment Signature (signatureEvvm) - if priorityFeeEvvm > 0:

##Hash Username Structure

The hashPreRegisteredUsername is calculated off-chain:

bytes32 hashPreRegisteredUsername = keccak256(abi.encodePacked(username, lockNumber));

Components:

  • username (string): The desired username (kept secret during commit phase)
  • lockNumber (uint256): Secret number (required later during registrationUsername)

Security: The hash conceals the actual username from front-runners. Only the user knows the lockNumber needed to complete registration.

Execution Flow​

1. Signature Verification (Core.sol)​

core.validateAndConsumeNonce(
    user,                                                      // Signer
    senderExecutor,                                            // msg.sender validation
    Hash.hashDataForPreRegistrationUsername(hashPreRegisteredUsername), // Hash payload
    originExecutor,                                            // tx.origin check
    nonce,                                                     // Core nonce
    true,                                                      // Async
    signature                                                  // EIP-191 signature
);

What Core.sol validates:

  • ✅ If senderExecutor != address(0): validates msg.sender matches senderExecutor
  • ✅ If originExecutor != address(0): validates tx.origin matches originExecutor
  • ✅ Signature matches user address
  • ✅ Nonce is valid and available (flexible consumption based on senderExecutor)
  • ✅ Marks nonce as consumed
  • ✅ Optionally delegates to UserValidator

2. Priority Fee Processing (if > 0)​

if (priorityFeeEvvm > 0) {
    requestPay(user, 0, priorityFeeEvvm, originExecutor, nonceEvvm, signatureEvvm);
}

Internally calls:

core.pay(
    user,                                  // Payer
    address(this),                         // NameService
    "",                                    // No identity
    principalToken,                        // PT
    priorityFeeEvvm,                       // Amount
    priorityFeeEvvm,                       // Priority fee
    address(this),                         // senderExecutor (NameService)
    address(this),                         // originExecutor (NameService)
    nonceEvvm,                             // Payment nonce
    true,                                  // Async
    signatureEvvm                          // Payment sig
);
Service Payment Accountability

When NameService dispatches payments on behalf of users, both senderExecutor and originExecutor are set to address(this) (NameService address). This provides clear tracking of payment origins and accountability in the EVVM ecosystem.

3. Commitment Storage​

Stores the commitment for 30 minutes:

string memory key = string.concat("@", AdvancedStrings.bytes32ToString(hashPreRegisteredUsername));

identityDetails[key] = IdentityBaseMetadata({
    owner: user,
    expirationDate: block.timestamp + 30 minutes,
    customMetadataMaxSlots: 0,
    offerMaxSlots: 0,
    flagNotAUsername: 0x01                    // Marked as pre-registration
});

Key Format: @<hash_string> (e.g., @0xa7f3c2d8e9b4f1a6...)

4. Staker Rewards (if executor is staker)​

if (core.isAddressStaker(msg.sender)) {
    makeCaPay(msg.sender, core.getRewardAmount() + priorityFeeEvvm);
}

Reward Breakdown:

  • Base reward: 1x core.getRewardAmount()
  • Priority fee: Full priorityFeeEvvm amount
  • Distributed via core.caPay()

Execution Methods​

Can be executed by any address. Rewards only distributed if msg.sender is a staker.

Fisher Execution (Off-Chain Executors)​

  1. User signs operation and payment (if priority fee)
  2. Fisher captures and validates transaction
  3. Fisher submits to NameService contract
  4. If fisher is staker, receives rewards

Direct Execution​

  1. User or service submits directly to contract
  2. If executor is staker, receives rewards
  3. No intermediary needed

Complete Example​

Scenario: User wants to reserve username "alice" for 30 minutes

Step 1: Generate Commitment​

string memory username = "alice";
uint256 lockNumber = 987654321;  // Keep secret!

bytes32 hashPreRegisteredUsername = keccak256(
    abi.encodePacked(username, lockNumber)
);
// Result: 0xa7f3c2d8e9b4f1a6c5d8e7f9b2a3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1

Step 2: Generate Operation Signature​

// Generate hash payload
bytes32 hashPayload = NameServiceHashUtils.hashDataForPreRegistrationUsername(
    hashPreRegisteredUsername
);

// Construct signature message (via Core)
// Format: {evvmId},{nameServiceAddress},{hashPayload},{originExecutor},{nonce},{isAsyncExec}

Step 3: Call Function​

nameService.preRegistrationUsername(
    user,                                   // 0x742d...
    hashPreRegisteredUsername,              // 0xa7f3...
    address(0),                             // Unrestricted
    nonce,                                  // 42
    signature,                              // Operation sig
    1000000000000000000,                    // 1 PT priority fee
    nonceEvvm,                              // 43
    signatureEvvm                           // Payment sig
);

Step 4: Wait 30 Minutes​

Commitment is now stored and valid for 30 minutes. Must complete registration within this window.

Important Notes​

Time Window​

  • Valid for: 30 minutes from commitment
  • Must register: Before expirationDate passes
  • If expired: Must submit new pre-registration

Lock Number Security​

  • Randomness: Use cryptographically secure random number
  • Secrecy: Never share before registration
  • Storage: Store safely client-side
  • Size: uint256 (0 to 2^256-1)

Front-Running Protection​

// Commit phase: Only hash is public
hashUsername = keccak256(abi.encodePacked("alice", 987654321))
// Front-runners see: 0xa7f3c2d8e9b4f1a6c5d8e7f9b2a3c4d5...
// Front-runners cannot determine: "alice"

// Reveal phase (after 30 min): Username is revealed
regist rationUsername(..., "alice", 987654321, ...)
// Contract validates: keccak256("alice", 987654321) == stored hash

Gas Costs​

Estimated Gas Usage:

  • Base operation: ~50,000 gas
  • Core verification: ~5,000 gas
  • Storage (commitment): ~20,000 gas
  • Payment (if priority fee): ~30,000 gas
  • Total: ~75,000 - 105,000 gas

Error Handling​

Common revert reasons:

// From Core.sol validation
"Invalid signature"                 // Signature verification failed
"Nonce already used"                // Nonce was consumed
"Invalid executor"                  // tx.origin doesn't match originExecutor

// From payment processing (if priorityFeeEvvm > 0)
"Insufficient balance"              // User lacks PT for fee
"Payment signature invalid"         // Payment signature failed