File Storage
On-chain files up to 10 MB, served over HTTP0x00000000000000000000000000000000000000f12 gas/byte of calldata
Live sample: a video stored on chain
Vitruveo.mp4 (2.91 MB, video/mp4) was uploaded in 6 chunks of up to 512 KB and finalized in block 5,432,211. The player below streams it straight from a Vitruveo node.
0x8f684b47bd39dbd2140dbf3eb17e7d89d30ff249b140810f45f67bbd79f19a7c- begin0xe48947d7…c15d8cc8
- upload 00x67920741…56fe2cbf
- upload 10x0bf01cfa…1941748c
- upload 20x4c4b2c2c…179377c7
- upload 30x62021f3e…f4c4150c
- upload 40xe33a91fc…798d8e39
- upload 50x9b02cf80…e7a11df0
- finalize0xc54d273e…f807a9e8
Why It Matters
Artwork, metadata and documents can live on chain instead of on IPFS or a cloud bucket. Files up to 10 MB are addressed by their SHA-256 and are immutable once finalized. File bytes live in the calldata of upload transactions (block bodies, kept by every node); state holds only the owner, size, content type and chunk locations. Transactions sent directly to this address pay 2 gas per calldata byte instead of 16.
Uploading
Upload from an EOA, in this order (consecutive nonces can be sent at once):
begin(sha256, size, contentType)upload(sha256, i, chunk)for i = 0, 1, 2 ... with chunks of up to 512 KBfinalize(sha256)- checks the SHA-256 of all chunks
upload()must be a transaction sent directly to0x00000000000000000000000000000000000000f1, not a call from a contract.- Calling
begin()again restarts an unfinished upload. - Content type: printable ASCII, up to 127 characters.
- For files with embedded Content Credentials, use
beginWithCredential()and pass the byte range of the embedded manifest store as the exclusion. See Content Credentials. - The transaction size limit is 544 KB, so a 512 KB chunk plus ABI and transaction overhead fits.
HTTP Gateway
Nodes serve finalized files over HTTP. Files are rebuilt from the upload transactions and checked against their SHA-256 before being served.
GET https://rpc.vitruveo.ai/file/<sha256 hex> GET https://rpc.vitruveo.ai/file/<sha256 hex>.png (extension is ignored) - Hash: 64 hex characters, with or without 0x - Content-Type: the stored content type (default application/octet-stream) - Range requests (Accept-Ranges / 206 Partial Content) - CORS: Access-Control-Allow-Origin: * (GET, HEAD, OPTIONS) - Cache-Control: public, max-age=31536000, immutable - ETag: "<sha256 hex>" - 400 invalid hash, 404 file not found
Gas
Calldata (direct txs) 2/byte (instead of 16) Every call 500 begin 20,000 upload (per chunk) 20,000 finalize 20,000 View calls 2,600
Interface
interface IFileStore {
event FileStored(bytes32 indexed sha256Hash, address indexed owner, uint256 size, string contentType);
function begin(bytes32 sha256Hash, uint256 size, string calldata contentType) external returns (bool);
function beginWithCredential(bytes32 sha256Hash, uint256 size, string calldata contentType,
uint256[] calldata exclusionStart, uint256[] calldata exclusionLength)
external returns (bool);
function upload(bytes32 sha256Hash, uint256 index, bytes calldata chunk) external returns (bool);
function finalize(bytes32 sha256Hash) external returns (bool);
function exists(bytes32 sha256Hash) external view returns (bool);
function info(bytes32 sha256Hash) external view
returns (address owner, uint256 size, string memory contentType, uint256 chunks, uint256 blockNumber);
/// status: 0 none, 1 uploading, 2 finalized
function session(address owner, bytes32 sha256Hash) external view
returns (uint256 status, uint256 size, uint256 received, uint256 chunks);
function credentialInfo(bytes32 sha256Hash) external view
returns (bytes32 contentHash, uint256[] memory exclusionStart, uint256[] memory exclusionLength);
/// Read chunk with eth_getTransactionByBlockNumberAndIndex and ABI-decode upload() calldata.
function chunkLocation(bytes32 sha256Hash, uint256 index) external view
returns (uint256 blockNumber, uint256 txIndex);
}Source: contracts/filestore/IFileStore.sol in the Vitruveo protocol repository.