allow (restricted)

Published: March 2025 | Last updated: March 2025

Overview

The allow RPC method adds a new authorized tenant to the Lynx blockchain storage system. This command enables the blockchain administrator to grant storage privileges to new tenants by registering their public key hash in the authentication system. Once added, the new tenant can authenticate and begin storing data on the blockchain.

Syntax

allow <hash160>

Description

When you invoke the allow method as the blockchain manager, the Lynx daemon creates and broadcasts a special transaction containing authentication data that registers a new tenant in the system. This transaction includes a timestamped payload with the tenant's identifier, which is permanently recorded on the blockchain. This process establishes an immutable record of tenant authorization that can be verified by all nodes in the network.

The authorization process is designed with strong access controls to ensure that only the designated blockchain manager can add new tenants, protecting the integrity of the storage system's authentication mechanism.

Parameters

Parameter	Type	Required	Description
hash160	string	Yes	The RIPEMD-160 hash of the new tenant's public key in hexadecimal format. This is a 40-character hexadecimal string (e.g., 00112233445566778899aabbccddeeff00112233) that uniquely identifies the tenant.

Returns

The method returns an array containing one or more status messages:

For successful operations:

[
  "success",
  "00112233445566778899aabbccddeeff00112233"
]

For failed operations, the array will contain a descriptive error message indicating the reason for failure:

[
  "hash160-wrong-size"
]

Possible status messages include:

• success - The tenant has been successfully added to the system

• hash160-wrong-size - The provided hash is not the correct length (must be 40 hexadecimal characters)

• Role-based restriction: Current role cannot perform this action - The authenticated user is not the blockchain manager

• error-generating-authpayload - An error occurred while generating the authentication payload

• error-generating-authtransaction - An error occurred while creating the authentication transaction

• authentication failure - The user is not authenticated or the authentication has expired

• failure - A general failure occurred (rarely seen, as more specific errors are usually provided)

Access Control

The allow command has strict access control requirements:

• Only the blockchain manager (initial authentication user defined in consensus parameters) can execute this command

• The manager must be authenticated via the auth command before using allow

• Regular tenants cannot add other tenants, even if they are authenticated

• This role-based restriction ensures centralized control over tenant authorization

Authentication Transaction

When a new tenant is added, the system:

1. Generates a special authentication payload containing:

   • Operation type (0 for adding a tenant)

   • Current timestamp

   • The tenant's hash160 identifier

2. Creates a blockchain transaction with this payload embedded as an OP_RETURN output

3. Broadcasts this transaction to the network, where it will be mined into a block

This transaction serves as a permanent, immutable record of tenant authorization that all nodes can verify.

Examples

Add a new tenant

As the blockchain manager:

lynx-cli allow 00112233445566778899aabbccddeeff00112233

Output:

[
  "success",
  "00112233445566778899aabbccddeeff00112233"
]

Using JSON-RPC:

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

Error Handling

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

• The provided hash160 is not exactly 40 characters long (20 bytes in hexadecimal)

• The user is not authenticated or is not authenticated as the blockchain manager

• There is an error in generating the authentication payload or transaction

• The authentication system cannot validate the current user's credentials

Implementation Notes

• The command verifies the user's authentication status using the is_auth_member function

• It validates that the authenticated user is the blockchain manager using consensus parameters

• The current timestamp is obtained using TicksSinceEpoch<std::chrono::seconds>(GetAdjustedTime())

• The authentication payload is generated with the generate_auth_payload function

• The authentication transaction is created and broadcast with the generate_auth_transaction function

• The system performs validation checks on both the tenant identifier and the transaction creation process