Skip to content

External Storage

External Storage feature is deprecated

Starting in STRATO v7.5, the External Storage feature is removed from STRATO in favor of application-side implementations.

Introduction

External Storage is a feature which allows users to maintain and verify records on STRATO while actually storing the files externally. External Storage offers the benefit of immutable, verifiable files but does not clog the blockchain with the large amounts of data that the file may contain. This is especially useful for storing media and large document files. This feature works by creating an smart contract representing the file that provides an interface to access and manage the file. External Storage functionality is available independently of regular STRATO contract transactions, which allows users to easily interact with their files without worrying about the technical implementation of smart contracts.

Cloud Storage Provider

Currently, STRATO supports the following cloud storage providers for External Storage:

  • Amazon S3

Users must have an cloud storage account setup with the appropriate permissions settings configured as described in Storage Host Provider Setup.

Note

STRATO only supports a single storage account per node.

Storage Host Provider Setup

AWS S3

In order to integrate with AWS S3, a user must first have an AWS bucket setup and a valid access key to the bucket.

Visit AWS S3 Documentation for instructions on setting up a new bucket and access key.

At minimum, the user associated with the provided access key must have "read" and "write" access permissions to the storage bucket.

STRATO Deployment

External Storage must be enabled through providing the Storage Provider's credentials in the proper environment variables at STRATO boot time.

AWS S3

  • EXT_STORAGE_S3_BUCKET
    • The AWS S3 bucket name to use as the external storage container.
    • Files uploaded with External Storage are placed in this bucket.
  • EXT_STORAGE_S3_ACCESS_KEY_ID
    • The access key ID of the user with write permissions to the provided AWS S3 bucket.
  • EXT_STORAGE_S3_SECRET_ACCESS_KEY
    • The secret access key of the user with write permissions to the provided AWS S3 bucket.

Example

EXT_STORAGE_S3_BUCKET=<storage-bucket-name> \
EXT_STORAGE_S3_ACCESS_KEY_ID=<access-key-id> \
EXT_STORAGE_S3_SECRET_ACCESS_KEY=<access-key> \
...
./strato

Usage

External Storage allows users to upload and download files, and manage their legitimacy by being able to attest to a file and retrieve the signers (other members who have attested) of a file. Attestation is done entirely through the file's External Storage Smart Contract so all data is guaranteed to be valid and secure.

This page lists each endpoints general functionality - visit the BlockApps API Reference for complete documentation on each endpoint's behavior.

Endpoint

All functionality is served through the following API prefix:

https://<strato_address>/apex-api/bloc/file

Upload File

Files may be uploaded to external storage using the /upload endpoint. Data about the file is provided in key-value pairs through HTTP form data. External Storage contracts store the hash of the binary data of the file to both ensure that the file's contents are valid, as well as minimize the size of the data within the smart contract. It will return the URI from which to access the file on the Storage Provider.

Endpoint

POST https://<strato_address>/apex-api/bloc/file/upload

Download Stored File

Any file that is uploaded to External Storage may be downloaded directly to a user's device. This endpoint will respond with a one-time use URL from which a user may download the requested file.

Endpoint

GET https://<strato_address>/apex-api/bloc/file/download

Get All Uploaded Files

Retrieve a list of all files uploaded to External Storage. Retrieves each file's contract address, External Storage URI, file key, content hash, and time created.

Endpoint

GET https://<strato_address>/apex-api/bloc/file/list

Attest to a File

Attestation of a file means that a user agrees with the contents and data of a file. A user "signs" their user address to the file's smart contract to attest to its legitimacy. A user should only attest to the validity of a file if they are sure that contents of it are valid. STRATO's External Storage contracts do not check for file validity. Attestation will not affect the contents of the file contained within the external storage. After attesting for a file, the endpoint will respond with confirmation that the user attested to this file, as well as a list of all the signers of this file.

Endpoint

POST https://<strato_address>/apex-api/bloc/file/attest

Get File Signers

Retrieve the list of users who have attested the legitimacy of a stored file.

Endpoint

GET https://<strato_address>/apex-api/bloc/file/verify

External Storage Smart Contract

A file uploaded using External Storage is represented on STRATO with a smart contract. The smart contract stores the hash, signers, metadata, and other related information about the file. Developers may query information about External Storage contracts using Cirrus, or perform other operations on it as one would with a normal smart contract. By design, the contract does not provide any methods to modify existing data except to add a new attestor.

contract ExternalStorage {
  string public fileKey;
  string public uri;
  string public host;
  string public fileHash;
  address[] public signers;
  uint public timeStamp;
  string public metadata;

  constructor(string _fileKey, string _uri, string _host, string _hash, string _metadata) {
    fileKey = _fileKey;
    uri = _uri;
    host = _host;
    fileHash = _hash;
    signers = [msg.sender];
    metadata = _metadata;
    timeStamp = now;
  }

  function attest() public returns(address[]) {
    signers.push(msg.sender);
    return(signers);
  }
}