Indexer.sol

Overview

Indexer.sol defines the NameIndex smart contract, which functions as a name-to-wallet address indexer with multifactor ownership verification. It manages mappings between a human-readable name and a wallet address, enforces ownership through a multi-step cryptographic proof process, and interacts with Mirror contracts to validate ownership. The contract includes mechanisms to ensure sufficient contract balance, owner verification via cryptographic proofs, and allows controlled updates to the associated wallet address.

This contract is designed to operate under strict validation rules, ensuring that only authorized entities can update or confirm ownership. It leverages external libraries and imported contracts such as VerifiersLib, Mirror, and Modifiers for security, validation, and permission management.

Contract: NameIndex

State Variables

Constructor

constructor (
    address wallet,
    uint256 rootPubkey,
    uint128 index,
    address root
) accept

• Purpose: Initializes the NameIndex contract instance with wallet address, root public key, index for address calculation, and root address.

• Parameters:

  • wallet: Initial wallet address tied to the indexed name.

  • rootPubkey: Public key of the root owner for signing and verification.

  • index: Index used for deterministic address calculation.

  • root: Root contract address with elevated permissions.

• Behavior:

  • Retrieves embedded library version from contract code salt and validates it against expected version from VerifiersLib.

  • Sets _root, _wallet, and _rootPubkey.

  • Calculates an expected address using a deterministic formula involving constants BASE_PART and SHIFT, combined with the index.

  • Validates that the sender is either the root or the expected address based on the index, reverting if unauthorized.

• Usage Example:

  NameIndex instance = new NameIndex(walletAddress, rootPubkey, 5, rootAddress);
  

Private Functions

ensureBalance

function ensureBalance() private pure

• Purpose: Ensures the contract maintains a minimum balance defined by CONTRACT_BALANCE to cover operation costs.

• Implementation Details:

  • Checks current contract balance.

  • If below threshold, mints additional funds (gosh.mintshellq) to maintain operational capacity.

• Note: The minting mechanism gosh.mintshellq likely interacts with a native token or gas system specific to the environment.

Public Functions

isOwner

function isOwner(
    address wallet,
    string zkid,
    bytes proof,
    uint256 epk,
    bytes epk_sig,
    uint64 epk_expire_at,
    bytes jwk_modulus,
    bytes kid,
    uint64 jwk_modulus_expire_at,
    uint8 index_mod_4,
    string iss_base_64,
    string provider,
    string header_base_64,
    uint256 pub_recovery_key,
    bytes pub_recovery_key_sig,
    uint256 jwk_update_key,
    bytes jwk_update_key_sig,
    mapping(uint256 => bytes) root_provider_certificates,
    uint256 owner_pubkey,
    uint128 index
) public view accept

• Purpose: Validates ownership claim for a wallet via multifactor proofs and delegates deployment/validation to a Mirror contract.

• Parameters:

  • wallet: The wallet address claimed as owner.

  • zkid: Zero-knowledge proof identifier.

  • proof: Cryptographic proof bytes.

  • epk, epk_sig, epk_expire_at: Ephemeral public key and its signature with expiration.

  • jwk_modulus, kid, jwk_modulus_expire_at: JWK modulus and related metadata.

  • index_mod_4: An index modulus to support validation.

  • iss_base_64, provider, header_base_64: Issuer and provider info encoded in base64, and header data.

  • pub_recovery_key, pub_recovery_key_sig: Public recovery key and signature.

  • jwk_update_key, jwk_update_key_sig: JWK update key and signature.

  • root_provider_certificates: Mapping of certificates from root providers.

  • owner_pubkey: Public key of the owner to verify ownership.

  • index: Index used to calculate expected caller address.

• Behavior:

  • Validates that the index is within acceptable bounds.

  • Checks that the caller is the expected address computed using the index.

  • Calls ensureBalance() to maintain contract operational funds.

  • Checks if the wallet matches the internal _wallet and sets a ready flag accordingly.

  • Invokes the isDeployMultifactor method on the Mirror contract at the caller's address, forwarding ownership and proof data.

• Usage Example:

  nameIndex.isOwner(walletAddr, zkid, proofBytes, epk, epkSig, epkExpire, jwkMod, kid, jwkExpire, idxMod4, iss, provider, header, pubRecKey, pubRecSig, jwkUpdKey, jwkUpdSig, rootCerts, ownerPubKey, index);
  

isOwnerRoot

function isOwnerRoot(
    address wallet,
    string zkid,
    bytes proof,
    uint256 epk,
    bytes epk_sig,
    uint64 epk_expire_at,
    bytes jwk_modulus,
    bytes kid,
    uint64 jwk_modulus_expire_at,
    uint8 index_mod_4,
    string iss_base_64,
    string provider,
    string header_base_64,
    uint256 pub_recovery_key,
    bytes pub_recovery_key_sig,
    uint256 jwk_update_key,
    bytes jwk_update_key_sig,
    mapping(uint256 => bytes) root_provider_certificates,
    uint256 owner_pubkey,
    address mirror
) public onlyOwnerPubkey(_rootPubkey) accept

• Purpose: Allows the root owner (authorized by _rootPubkey) to confirm ownership and update the wallet address directly.

• Parameters: Same as isOwner, with an additional mirror address parameter specifying the target Mirror contract.

• Modifiers:

  • onlyOwnerPubkey(_rootPubkey): Restricts access to the root public key owner.

• Behavior:

  • Ensures contract balance sufficiency.

  • Updates internal _wallet to the provided wallet address.

  • Calls isDeployMultifactor on the specified Mirror contract to finalize multifactor deployment with ownership proofs.

• Usage Example:

  nameIndex.isOwnerRoot(walletAddr, ..., mirrorAddr);
  

setNewWallet

function setNewWallet(address wallet) public senderIs(_wallet) accept

• Purpose: Allows the current wallet owner to update the _wallet address.

• Parameters:

  • wallet: The new wallet address to associate with the indexed name.

• Modifiers:

  • senderIs(_wallet): Only the current _wallet address can call this function.

• Behavior: Updates _wallet with the new address.

• Usage Example:

  nameIndex.setNewWallet(newWalletAddress);
  

destroyNode

function destroyNode() public senderIs(address(this)) accept

• Purpose: Self-destruct function to destroy the contract.

• Modifiers:

  • senderIs(address(this)): Only the contract itself can invoke self-destruction.

• Behavior: Calls selfdestruct sending remaining funds to the contract's own address.

• Usage Notes: Typically used for cleanup or upgrade purposes by internal mechanisms.

getDetails

function getDetails() external view returns(string name, address wallet)

• Purpose: Retrieves the indexed name and associated wallet address.

• Returns:

  • name: Indexed name stored in the contract.

  • wallet: Wallet address linked to the name.

• Usage Example:

  (string memory name, address wallet) = nameIndex.getDetails();
  

getVersion

function getVersion() external pure returns(string, string)

• Purpose: Returns the contract version string and a label identifying the contract as "Indexer".

• Returns:

  • Version string "1.0.0".

  • The string "Indexer".

• Usage Example:

  (string memory version, string memory label) = nameIndex.getVersion();
  

Implementation Details

• Address Derivation: The contract calculates expected caller addresses using a formula involving BASE_PART, SHIFT, and the provided index parameter. This deterministic address generation restricts who can call sensitive functions, enhancing security.

• Multifactor Ownership Validation: Ownership is verified through a multi-layered cryptographic process involving ephemeral keys (epk), JSON Web Keys (JWK), zero-knowledge proofs, and signatures. This process is delegated to the Mirror contract via the isDeployMultifactor method.

• Balance Management: The contract ensures it maintains a minimal operational balance (CONTRACT_BALANCE) by invoking a mint function if the balance drops below a threshold, preventing failures due to insufficient funds.

• Permission Modifiers: Uses imported modifiers such as accept, onlyOwnerPubkey, and senderIs to enforce access control on sensitive operations.

• Static Name Storage: The _name variable is declared static, meaning it is set once during contract deployment and immutable thereafter.

Interaction with Other Contracts and Libraries

• Modifiers Contract: Provides reusable permission and validation modifiers for access control.

• VerifiersLib Library: Used to validate the library version embedded in the contract code salt, ensuring compatibility.

• Mirror Contract: Acts as a multifactor ownership validation service. The NameIndex contract interacts heavily with Mirror instances, calling isDeployMultifactor to confirm ownership claims.

• MobileVerifiersContractRoot and Mirror Imports: These imports suggest integration with a broader verification and indexing system, although their exact role is external to this contract.

• Balance Minting (gosh.mintshellq): Indicates integration with a gas or token management system to maintain contract operability.

Diagram: NameIndex Contract Structure

classDiagram
class NameIndex {
-string version
-string _name
-address _wallet
-address _root
-uint256 _rootPubkey
+constructor(wallet, rootPubkey, index, root)
-ensureBalance()
+isOwner(wallet, zkid, proof, epk, epk_sig, epk_expire_at, jwk_modulus, kid, jwk_modulus_expire_at, index_mod_4, iss_base_64, provider, header_base_64, pub_recovery_key, pub_recovery_key_sig, jwk_update_key, jwk_update_key_sig, root_provider_certificates, owner_pubkey, index)
+isOwnerRoot(wallet, zkid, proof, epk, epk_sig, epk_expire_at, jwk_modulus, kid, jwk_modulus_expire_at, index_mod_4, iss_base_64, provider, header_base_64, pub_recovery_key, pub_recovery_key_sig, jwk_update_key, jwk_update_key_sig, root_provider_certificates, owner_pubkey, mirror)
+setNewWallet(wallet)
+destroyNode()
+getDetails() string,string
+getVersion() string,string
}
NameIndex ..|> Modifiers
NameIndex o-- Mirror : calls
NameIndex ..> VerifiersLib : uses

References

• Modifiers

• VerifiersLib

• Mirror Contract

• Mobile Verifiers Contract Root

• Smart Contract Authorization

• Cryptographic Proofs

• Address Derivation and Validation