store

Published: March 2025 | Last updated: March 2025

Overview

The store RPC method allows you to upload and store files on the Lynx blockchain. This command is part of Lynx's decentralized file storage system, enabling users to persistently store data in a distributed manner.

Syntax

store <filepath> [uuid]

Description

When you invoke the store method, the Lynx daemon reads the specified file from your filesystem, processes it for blockchain storage, and initiates a storage transaction. The file is sharded appropriately and stored across multiple blockchain transactions, with a unique identifier (UUID) assigned to enable future retrieval.

Parameters

Parameter	Type	Required	Description
filepath	string	Yes	The full path to the file you want to store on the blockchain (e.g., /home/username/documents/research.pdf). The file must exist and have a size greater than zero bytes.
uuid	string	No	An optional custom unique identifier for the file. If provided, it must be 32 characters in hexadecimal format and must not already exist on the blockchain. If omitted, a random UUID will be automatically generated.

Returns

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

Field	Type	Description
result	string	Indicates whether the operation succeeded (success) or failed (failure).
message	string	Provides additional information about the result. For successful operations, returns n/a. For failures, indicates the reason (e.g., Not authenticated as tenant, Not authenticated, A duplicate unique identifier was discovered, The custom unique identifier provided has an invalid length, Invalid UUID hex notation, Zero length asset filesize).
identifier	string	The UUID assigned to the file. For successful operations, this is either the custom UUID you provided or an automatically generated one. For failures, returns n/a unless the failure is related to an invalid custom UUID.
tenant	string	The authenticated user's public key hash. For authentication failures, returns n/a.
filesize	number	The size of the stored file in bytes. For failures, returns 0.
storagefee	string/number	The storage transaction fee in Lynx. The fee is calculated as one liv per byte (filesize / 100,000,000 Lynx). For failures, returns 0.
storagetime	string	The timestamp when the storage operation was performed, in YYYY-MM-DD HH:MM:SS format. For failures, returns n/a.
currentblock	number	The current blockchain height at the time of the operation.
stakingstatus	string	Indicates whether staking is currently enabled or disabled on the node.

Authentication Requirements

The store method requires authentication:

• The Tenant must authenticate using the appropriate credentials before using this command

• Authentication sessions expire after 6 hours (21,600 seconds)

Error Handling

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

• The user is not authenticated or the authentication session has expired

• The custom UUID already exists on the blockchain

• The custom UUID has an invalid length (must be 32 characters)

• The custom UUID contains non-hexadecimal characters

• The file has zero length or doesn't exist

Examples

Store a file with an automatically generated UUID

lynx-cli store /home/username/documents/research.pdf

Or using JSON-RPC:

curl --user username --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "store", "params": ["/home/username/documents/research.pdf"]}' -H 'content-type: text/plain;' http://127.0.0.1:9332/

Store a file with a custom UUID

lynx-cli store /home/username/documents/research.pdf 00112233445566778899aabbccddeeff

Implementation Notes

• The method adds the storage task to a queue rather than performing a synchronous upload

• Files are stored with one liv per byte as the transaction fee

• The system automatically generates a UUID if none is provided

• Custom UUIDs are validated for length, hexadecimal format, and uniqueness

• The current blockchain height and staking status are included in all responses