External Storage

External Storage is a feature which allow blockchain users to maintain and verify records on the blockchain while actually storing their files externally. This has the benefit of creating an immutable record of the file, by reference, and the related credentials and attestations, while at the same time not clogging the blockchain with large video or media files or external datasets which could (over time) affect blockchain performance. Currently, the storage mechanism utilized by External Storage is Amazon (AWS) S3, and to be able to upload data, one or more users will need an AWS S3 account, with the appropriate permissions settings configured.

Setup AWS S3 Credentials

To enable external the storage feature on the STRATO node or network, see the Enable External Storage Instructions under the Install a Network section of this documentation.

Additionally, the administrator of the STRATO node/network will need to have administrator permissions on the AWS S3 bucket that is being utilized by STRATO. By enabling the feature in STRATO, the AWS S3 bucket will be able to provide one-time links to users for the S3 buckets based on STRATO-level permissions.

Upload File to S3

To upload a file to an AWS S3 bucket and create a smart contract with the URI of the file on S3, you can use the following curl command:

curl -X POST "https://<your_ip_address>/apex-api/bloc/file/upload" -H "accept: application/json;charset=utf-8" -H "Content-Type: multipart/form-data" -F "username=<your_username>" -F "password=<your_password>" -F "address=<your_user_address>" -F "provider=s3" -F "metadata=<your_description>" -F "[email protected]<path_to_your_file>;type=image/png"

This allows a user to cryptographically prove that the file was uploaded to S3 at a specific date. If the file is uploaded successfully, we'll get a response with the address of the smart contract that is storing our file.

  "contractAddress": "0x123456789",
  "URI": "`...`", 
  "metadata": "a sample video on s3"

Attest Legitimacy of File

This endpoint can be used to sign a method in the smart contract to attest the legitimacy of the uploaded file on S3.

curl -X POST "https://<your_ip_address>/apex-api/bloc/file/attest" -H  "accept: application/json;charset=utf-8" -d  "ea5e32eff6edcfa1da15a124b73c6995096799a7"

This returns a JSON with a list of addresses that have signed the contract:

  "signers": [
      "1": "0x123456",
      "2": "0x246810",
      "3": "0x235711"

Get Signers of File

This endpoint returns the list of users who have attested the legitimacy of the stored resource.

curl -x GET "http://localhost/apex-api/bloc/file/verify"
    -H  "accept: application/json;charset=utf-8"
    -d  "ea5e32eff6edcfa1da15a124b73c6995096799a7"

We'll get a JSON response with the list of addresses who have attested the legitimacy of the stored resource.

  "uri": "0123456",
  "timestamp": "02182018_2253",
  "signers": [
      "1": "0x123456789",
      "2": "02468101214"

Download Stored File

We can download the file from S3 with this endpoint:

curl -X POST "https://<your_ip_address>/apex-api/bloc/file//download" -H  "accept: application/json;charset=utf-8" -d  "ea5e32eff6edcfa1da15a124b73c6995096799a7"

This will immediately begin download of the stored resource to the user's computer.

External Storage Smart Contract

The External Storage feature is governed by its own smart contract. STRATO comes with a default version of this contract.

Sample Scenario

Imagine that two people, Amy and Bob, on a network decide to share a video. It's impractical to store something this large on a blockchain, so they decide to store it off-chain on the cloud provider Amazon (AWS). Amy uploads the video to an Amazon S3 storage bucket and writes down the resource URI for the file and the S3 path to access it.

Bob is able verify that Amy's file was uploaded at the time she claims it was. He can check the legitimacy of the timestamped file upload by viewing the file through the STRATO dashboard or by calling the API function that returns the timestamp of the upload and the public key of the uploader.

When Bob views the hash of the S3 resource, he is responsible for manually verifying that the S3 resource matches the deserialized hash of the datasource. In addition, if there are any authentication credentials Bob needs to do this, Amy will be responsible for communicating any S3 authentication credentials to Bob separately, outside of the blockchain.

If their network has implemented a verification process, Bob will be able call an additional function, which accepts the external storage hash as an argument. If the submitted hash matches the hash previously added to the contract, the method will return true.