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
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:
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.pdfOr 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 00112233445566778899aabbccddeeffImplementation 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
Last updated