list

Published: March 2025 | Last updated: March 2025

Overview

The list RPC method retrieves metadata for files stored on the Lynx blockchain by the authenticated tenant. This command provides a comprehensive view of all your stored files, arranged chronologically with the most recently stored files appearing first in the results.

Syntax

list [count]

Description

When you invoke the list method, the Lynx daemon scans the blockchain for files associated with your tenant account and retrieves metadata about each file. This includes the unique identifier, file size, storage location, and timestamp information. This command is essential for managing your blockchain-stored files and serves as a directory service for your decentralized storage.

Parameters

Parameter	Type	Required	Description
count	string/integer	No	The maximum number of file records to retrieve. If omitted, the default is 10 records. To retrieve more files, you can specify a high number or 0 for all files.

Returns

The method returns a nested array structure containing file metadata:

[
  [
    {
      "uuid": "00112233445566778899aabbccddeeff",
      "length": 12345,
      "height": 987654,
      "timestamp": "2023-05-15 14:30:22"
    },
    {
      "uuid": "aabbccddeeff00112233445566778899",
      "length": 54321,
      "height": 987650,
      "timestamp": "2023-05-14 09:15:37"
    },
    ...
  ]
]

Each file entry contains the following fields:

Field	Type	Description
uuid	string	The unique identifier of the file. This is a 32-character hexadecimal string that serves as the primary reference for the file in the Lynx storage system.
length	number	The total size of the file in bytes. This represents the complete file size, even if the file data is distributed across multiple blockchain blocks.
height	number	The starting block number where the file storage began. Files may span multiple blocks depending on their size.
timestamp	string	The date and time when the file storage operation was initiated, in YYYY-MM-DD HH:MM:SS format.

Authentication Requirements

The list method requires user authentication:

• You must authenticate using the appropriate credentials before using this command

• If not authenticated, the method will return a simple "Not authenticated" message

• The method only retrieves files associated with the authenticated tenant

Performance Considerations

• The list command scans the blockchain to find files, which can be resource-intensive

• For large storage histories, limiting the results with the count parameter can improve performance

• The command logs the execution time to the debug log, which can be useful for monitoring performance

• The default limit of 10 recent files helps optimize performance for routine usage

Examples

List the 10 most recently stored files (default)

lynx-cli list

Or using JSON-RPC:

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

List the 5 most recently stored files

lynx-cli list 5

List all stored files

lynx-cli list 0

Implementation Notes

• Only files with complete metadata (file length > 0) are included in the results

• The command measures and logs its execution time for performance monitoring

• The results are presented with the most recent files first (chronological order, newest to oldest)