Vaults

⚠️ Future Content: The extensive API documentation and advanced vault management features below will be provided in future documentation updates. Enterprise vault orchestration and blockchain integration patterns are being developed for production deployments.

Vaults are ERC-1155 tokens that contain digital twin data and manage access permissions. They serve as secure, blockchain-based containers for all your asset data.

What are Vaults?

Vaults are the core storage and organizational unit in Filedgr. Each vault:

Is an NFT - Represented as an ERC-1155 token on the blockchain
Stores data - Contains all files, documents, and metadata for an asset
Manages permissions - Controls who can access and modify data
Tracks history - Maintains immutable audit trails of all changes
Enables sharing - Facilitates secure collaboration and verification

Vault Structure

graph TD
    A[Vault] --> B[Streams]
    B --> C[Data Attachments]
    A --> D[Permissions]
    A --> E[Metadata]
    A --> F[Audit Trail]

Key Components

Streams

Data channels within vaults that organize related information:

Document streams - Static files and documents
Data streams - Real-time or periodic data updates
Event streams - Activity logs and notifications

Data Attachments

The actual content stored in the vault:

Files - Documents, images, videos, etc.
Structured data - JSON, CSV, database records
Metadata - Tags, descriptions, custom fields

Permissions

Access control rules that determine:

Who can view the vault and its contents
Who can edit data within the vault
Who can manage permissions and settings
What actions are allowed for each user

Vault Permissions

Permission Levels

enum VaultPermission {
    NONE,    // No access
    VIEWER,  // Read-only
    EDITOR,  // Modify content
    ADMIN,   // Full control
    CUSTOM   // Custom permissions
}

Permission Matrix

Action	Owner	Admin	Editor	Viewer	Custom
View data	✅	✅	✅	✅	Config
Download files	✅	✅	✅	✅	Config
Upload files	✅	✅	✅	❌	Config
Edit metadata	✅	✅	✅	❌	Config
Manage permissions	✅	✅	❌	❌	Config
Transfer ownership	✅	❌	❌	❌	❌
Delete vault	✅	❌	❌	❌	❌

Creating Vaults

Basic Vault Creation

curl -X POST "https://api.filedgr.io/vaults" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "general-template-v1",
    "name": "Product Certification Vault",
    "description": "Contains all certification documents for Product X",
    "metadata": {
      "productId": "PROD-123",
      "category": "electronics",
      "manufacturingDate": "2024-01-15"
    }
  }'

Response:

{
  "vaultId": "vault_abc123",
  "name": "Product Certification Vault",
  "templateId": "general-template-v1",
  "owner": "user_def456",
  "status": "created",
  "blockchainTx": "0x1234567890abcdef...",
  "createdAt": "2024-01-15T10:30:00Z",
  "ipfsHash": "QmX4k5m8r7j2H9z3...",
  "network": "polygon"
}

Advanced Vault Configuration

const advancedVault = {
  templateId: "supply-chain-v2",
  name: "Organic Coffee Batch #2024-001",
  description: "Complete supply chain tracking for organic coffee batch",
  
  // Custom metadata
  metadata: {
    productType: "coffee",
    origin: "Guatemala",
    certification: "organic",
    batchSize: 1000,
    harvestDate: "2024-01-10"
  },
  
  // Access control settings
  permissions: {
    defaultPermission: "NONE",
    users: [
      {
        address: "user_supplier123",
        permission: "EDITOR",
        expiresAt: "2024-12-31T23:59:59Z"
      },
      {
        address: "user_auditor456", 
        permission: "VIEWER",
        restrictions: ["no_download"]
      }
    ]
  },
  
  // Storage preferences
  storage: {
    encryption: "AES-256",
    replication: 3,
    regions: ["us-east", "eu-west", "asia-pacific"]
  },
  
  // Compliance settings
  compliance: {
    standards: ["USDA-Organic", "Fair-Trade"],
    auditRequired: true,
    retentionPeriod: "7y"
  }
};

const response = await fetch('https://api.filedgr.io/vaults', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(advancedVault)
});

Managing Vault Data

Adding Files

# Upload a single file
curl -X POST "https://api.filedgr.io/vaults/vault_abc123/files" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@certificate.pdf" \
  -F "metadata={\"type\":\"certificate\",\"category\":\"quality\"}"

Adding Structured Data

curl -X POST "https://api.filedgr.io/vaults/vault_abc123/data" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "streamId": "quality-metrics",
    "data": {
      "temperature": 23.5,
      "humidity": 65.2,
      "ph": 6.8,
      "timestamp": "2024-01-15T10:30:00Z"
    },
    "metadata": {
      "sensor": "ENV-001",
      "location": "warehouse-a"
    }
  }'

Batch Operations

// Upload multiple files at once
const batchUpload = async (vaultId, files) => {
  const formData = new FormData();
  
  files.forEach((file, index) => {
    formData.append(`file_${index}`, file.blob, file.name);
    formData.append(`metadata_${index}`, JSON.stringify({
      type: file.type,
      category: file.category,
      tags: file.tags
    }));
  });
  
  const response = await fetch(`https://api.filedgr.io/vaults/${vaultId}/batch-upload`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`
    },
    body: formData
  });
  
  return response.json();
};

Permission Management

Setting User Permissions

curl -X POST "https://api.filedgr.io/vaults/vault_abc123/permissions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_def456",
    "permission": "EDITOR",
    "expiresAt": "2024-12-31T23:59:59Z",
    "restrictions": ["no_delete"]
  }'

Custom Permission Sets

const customPermissions = {
  userId: "user_auditor789",
  permission: "CUSTOM",
  permissions: {
    canView: true,
    canDownload: true,
    canUpload: false,
    canEdit: false,
    canShare: false,
    canManagePermissions: false,
    
    // Fine-grained controls
    canViewAuditTrail: true,
    canViewMetadata: true,
    canViewFiles: true,
    canViewStreams: ["audit-logs", "compliance-data"],
    
    // Time-based restrictions
    accessHours: "9-17", // 9 AM to 5 PM
    accessDays: ["monday", "tuesday", "wednesday", "thursday", "friday"],
    timezone: "UTC"
  }
};

Revoking Access

curl -X DELETE "https://api.filedgr.io/vaults/vault_abc123/permissions/user_def456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Vault Metadata

Standard Metadata Fields

{
  "metadata": {
    "name": "Product Certification Vault",
    "description": "Complete certification documents",
    "category": "compliance",
    "tags": ["certification", "quality", "ISO-9001"],
    
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T14:22:00Z",
    "owner": "user_abc123",
    "template": "certification-v1",
    
    "status": "active",
    "visibility": "private",
    "archived": false
  }
}

Custom Metadata

{
  "customMetadata": {
    "businessContext": {
      "department": "quality-assurance",
      "project": "product-launch-2024",
      "costCenter": "CC-4567",
      "approver": "manager@company.com"
    },
    
    "technicalData": {
      "version": "1.2.0",
      "environment": "production", 
      "integrationId": "ERP-VAULT-123",
      "externalReference": "QA-2024-001"
    },
    
    "complianceData": {
      "retentionPeriod": "7y",
      "classificationLevel": "internal",
      "dataSubjects": ["employees", "customers"],
      "legalBasis": "contract"
    }
  }
}

Vault Transfer

Transfer Ownership

curl -X POST "https://api.filedgr.io/vaults/vault_abc123/transfer" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "newOwner": "user_xyz789",
    "reason": "Department reorganization",
    "effectiveDate": "2024-02-01T00:00:00Z"
  }'

Batch Transfer

// Transfer multiple vaults to new owner
const transferVaults = async (vaultIds, newOwner) => {
  const transfers = vaultIds.map(vaultId => ({
    vaultId,
    newOwner,
    reason: "Bulk organizational transfer"
  }));
  
  const response = await fetch('https://api.filedgr.io/vaults/batch-transfer', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ transfers })
  });
  
  return response.json();
};

Vault Queries

List Vaults

curl -X GET "https://api.filedgr.io/vaults?page=1&limit=20&category=compliance" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Query Parameters:

page - Page number (default: 1)
limit - Items per page (default: 20, max: 100)
category - Filter by category
template - Filter by template ID
owner - Filter by owner
status - Filter by status (active, archived, etc.)
search - Search in name and description
sortBy - Sort field (createdAt, updatedAt, name)
sortOrder - Sort direction (asc, desc)

Advanced Filtering

curl -X GET "https://api.filedgr.io/vaults" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -G \
  -d "filter[metadata.category]=electronics" \
  -d "filter[createdAt][gte]=2024-01-01" \
  -d "filter[tags][in]=certification,quality" \
  -d "sortBy=updatedAt" \
  -d "sortOrder=desc"

Search Vaults

const searchVaults = async (query) => {
  const params = new URLSearchParams({
    q: query,
    fields: 'name,description,metadata',
    highlight: true,
    fuzzy: true
  });
  
  const response = await fetch(`https://api.filedgr.io/vaults/search?${params}`, {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  
  return response.json();
};

// Usage
const results = await searchVaults("ISO certification quality");

Vault Analytics

Get Vault Statistics

curl -X GET "https://api.filedgr.io/vaults/vault_abc123/stats" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "vaultId": "vault_abc123",
  "stats": {
    "totalFiles": 25,
    "totalSize": "156.7MB",
    "fileTypes": {
      "pdf": 15,
      "jpg": 8,
      "json": 2
    },
    "accessCount": 142,
    "lastAccessed": "2024-01-15T14:30:00Z",
    "verificationStatus": {
      "verified": 24,
      "pending": 1,
      "failed": 0
    },
    "complianceScore": 98.5
  }
}

Usage Analytics

// Get detailed analytics
const getVaultAnalytics = async (vaultId, timeframe = '30d') => {
  const response = await fetch(`https://api.filedgr.io/vaults/${vaultId}/analytics?timeframe=${timeframe}`, {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  
  const analytics = await response.json();
  
  return {
    accessPatterns: analytics.accessPatterns,
    userActivity: analytics.userActivity,
    dataGrowth: analytics.dataGrowth,
    verificationTrends: analytics.verificationTrends,
    complianceMetrics: analytics.complianceMetrics
  };
};

Error Handling

Common Errors

Vault Not Found (404)

{
  "error": "vault_not_found",
  "message": "Vault with ID 'vault_abc123' does not exist",
  "statusCode": 404
}

Permission Denied (403)

{
  "error": "permission_denied", 
  "message": "You don't have permission to access this vault",
  "statusCode": 403,
  "requiredPermission": "VIEWER"
}

Validation Error (400)

{
  "error": "validation_error",
  "message": "Invalid vault data provided",
  "statusCode": 400,
  "details": [
    {
      "field": "name",
      "message": "Name is required"
    },
    {
      "field": "templateId",
      "message": "Invalid template ID"
    }
  ]
}

Error Handling Pattern

const handleVaultOperation = async (operation) => {
  try {
    return await operation();
  } catch (error) {
    switch (error.status) {
      case 404:
        console.error('Vault not found');
        // Handle missing vault
        break;
        
      case 403:
        console.error('Permission denied');
        // Request access or show error
        break;
        
      case 400:
        console.error('Validation error:', error.details);
        // Show validation errors to user
        break;
        
      case 429:
        console.error('Rate limited');
        // Implement retry with backoff
        await new Promise(resolve => setTimeout(resolve, error.retryAfter * 1000));
        return handleVaultOperation(operation);
        
      default:
        console.error('Unexpected error:', error);
        throw error;
    }
  }
};

SDKs Usage

JavaScript SDK

import { Filedgr } from '@filedgr/sdk';

const filedgr = new Filedgr({
  apiKey: process.env.FILEDGR_API_KEY,
  apiSecret: process.env.FILEDGR_API_SECRET
});

// Create vault
const vault = await filedgr.vaults.create({
  templateId: 'general-template-v1',
  name: 'My Vault',
  metadata: {
    category: 'documents'
  }
});

// Add file
const file = await filedgr.vaults.uploadFile(vault.id, {
  file: fileBuffer,
  filename: 'document.pdf',
  metadata: {
    type: 'certificate'
  }
});

// Set permissions
await filedgr.vaults.setPermission(vault.id, 'user_123', 'VIEWER');

// Get vault data
const vaultData = await filedgr.vaults.get(vault.id);

Python SDK

import filedgr

client = filedgr.Client(
    api_key=os.environ['FILEDGR_API_KEY'],
    api_secret=os.environ['FILEDGR_API_SECRET']
)

# Create vault
vault = client.vaults.create(
    template_id='general-template-v1',
    name='My Python Vault',
    metadata={'category': 'documents'}
)

# Upload file
with open('document.pdf', 'rb') as f:
    file_result = client.vaults.upload_file(
        vault.id,
        file=f,
        filename='document.pdf',
        metadata={'type': 'certificate'}
    )

# List user's vaults
vaults = client.vaults.list(limit=50)
for vault in vaults.data:
    print(f"Vault: {vault.name} ({vault.id})")

Best Practices

Security

Principle of least privilege - Grant minimal necessary permissions
Regular access reviews - Periodically audit vault permissions
Strong authentication - Require MFA for sensitive vaults
Audit trail monitoring - Review access logs regularly

Performance

Batch operations - Use bulk APIs when processing multiple items
Pagination - Implement proper pagination for large result sets
Caching - Cache frequently accessed vault metadata
Compression - Compress large files before upload

Organization

Naming conventions - Use consistent, descriptive vault names
Metadata standards - Establish organization-wide metadata schemas
Template consistency - Use appropriate templates for each use case
Archive old vaults - Keep active vaults list manageable

Compliance

Retention policies - Implement appropriate data retention
Access logging - Monitor who accesses what when
Data classification - Tag vaults with appropriate sensitivity levels
Regular audits - Conduct periodic compliance reviews

Next Steps

Understand Digital Twins - See how vaults become digital twins
Explore Data Streams - Add real-time data to vaults
Learn Verification - Understand the verification process
Set Up Sharing - Securely share vault data

Vaults are the foundation of your digital twin infrastructure. Master vault management and you'll be able to build powerful, verifiable applications with Filedgr.

What are Vaults?​

Vault Structure​

Key Components​

Streams​

Data Attachments​

Permissions​

Vault Permissions​

Permission Levels​

Permission Matrix​

Creating Vaults​

Basic Vault Creation​

Advanced Vault Configuration​

Managing Vault Data​

Adding Files​

Adding Structured Data​

Batch Operations​

Permission Management​

Setting User Permissions​

Custom Permission Sets​

Revoking Access​

Vault Metadata​

Standard Metadata Fields​

Custom Metadata​

Vault Transfer​

Transfer Ownership​

Batch Transfer​

Vault Queries​

List Vaults​

Advanced Filtering​

Search Vaults​

Vault Analytics​

Get Vault Statistics​

Usage Analytics​

Error Handling​

Common Errors​

Vault Not Found (404)​

Permission Denied (403)​

Validation Error (400)​

Error Handling Pattern​

SDKs Usage​

JavaScript SDK​

Python SDK​

Best Practices​

Security​

Performance​

Organization​

Compliance​

Next Steps​