auth

Published: March 2025 | Last updated: May 2025

Overview

The auth RPC method authenticates a Tenant for a time-limited session on the Lynx blockchain. This authentication process establishes the user's identity and permissions, enabling them to perform storage operations appropriate to their role. Authentication sessions have a fixed duration of approximately 6 hours (72 blocks), after which re-authentication is required.

Syntax

lynx-cli auth

Description

When you invoke the auth method with a valid private key, the Lynx daemon verifies your identity against its list of authorized users and establishes a session that grants you access to role-appropriate commands. For security purposes, the command automatically disables staking for authenticated tenants. The private key used by the auth method is stored in the lynx.conf file. Since the private key is respective to the mainnet or testnet environments, the 'rpctenent' key is prefixed with the environment name. Examples of both are below.

~/.lynx/lynx.conf

# mainnet tenant key
main.rpctenant=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

# Commented testnet tenant key
# test.rpctenant=d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592

During authentication, the system evaluates your wallet's capacity to support storage operations, which directly determines the maximum storage capacity by the local daemon. This helps ensure that users have sufficient resources to complete their intended storage operations.

Parameters

Parameter	Type	Required	Description
[environment].rpctenant referenced from ~/.lynx/lynx.conf file	string	Yes	A valid WIF-format private key associated with an authorized tenant. This key proves your identity to the system.

Returns

The method returns an array containing a single object with the following fields:

Field	Type	Description
result	string	Indicates whether authentication succeeded (success) or failed (failure).
message	string	Provides additional information about the result: You are authenticated as a tenant, Invalid key, Unauthorized tenant, or No wallet.
capacity	number	The maximum storage capacity available to the Tenant in kilobytes (KB).
sessionstart	string	The timestamp when the authentication session began in YYYY-MM-DD HH:MM:SS format.
sessionend	string	The timestamp when the authentication session will expire in YYYY-MM-DD HH:MM:SS format.
sessionstartblock	string/number	The blockchain height when the authentication session began.
sessionendblock	string/number	The blockchain height when the authentication session will expire (start block + 72).
stakingstatus	string	Indicates whether staking is currently enabled or disabled on the node. Always set to disabled for regular tenants during their session.

Authentication Security

The authentication system implements several security measures:

• Progressive Delay: Failed authentication attempts introduce an exponentially increasing delay (doubling with each failure) to suppress brute force attacks.

• Session Expiration: Authentication sessions for regular tenants expire after approximately 6 hours (72 blocks).

• Staking Management: Staking is automatically disabled for regular tenants during their session to prevent resource conflicts. If staking is enabled in the lynx.conf file, staking will be enabled after the authorized tenant session expires.

Tenant Capacity Calculation

The system calculates a tenant's storage capacity based on the number of UTXO in their wallet:

• This calculation helps tenants understand their maximum storage allocation

Examples

Authenticate as a tenant

lynx-cli auth

Output for a successful tenant authentication:

[
  {
    "result": "success",
    "message": "You are authenticated as a tenant.",
    "capacity": 63569,
    "sessionstart": "2025-03-24 21:34:40",
    "sessionend": "2025-03-25 03:34:40",
    "sessionstartblock": 3108065,
    "sessionendblock": 3108137,
    "stakingstatus": "disabled"
  }
]

Using JSON-RPC:

curl --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "auth", "params": []}' -H 'content-type: text/plain;' http://127.0.0.1:9332/

Error Handling

The method will return a failure result in the following scenarios:

• Invalid Key: The provided private key is empty or invalid (cannot be used to derive a valid user)

• Unauthorized Tenant: The key is valid but not registered as an authorized tenant in the system

• No Wallet: The system doesn't have a wallet available for the authentication process

Each of these errors will trigger the progressive delay mechanism to suppress brute force attacks.