Skip to main content
GET
https://api-mainnet.onzks.com
/
v1
/
trust
/
modules
Get Trust Modules
curl --request GET \
  --url https://api-mainnet.onzks.com/v1/trust/modules \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "modules": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "type": "<string>",
      "category": "<string>",
      "version": "<string>",
      "status": "<string>",
      "schema": {
        "fields": [
          {
            "name": "<string>",
            "type": "<string>",
            "required": true,
            "description": "<string>",
            "validation": {}
          }
        ],
        "validation": {},
        "examples": [
          {}
        ]
      },
      "configuration": {
        "enabled": true,
        "settings": {},
        "permissions": [
          {}
        ],
        "dependencies": [
          {}
        ]
      },
      "capabilities": [
        {}
      ],
      "examples": [
        {
          "title": "<string>",
          "description": "<string>",
          "code": "<string>",
          "language": "<string>"
        }
      ],
      "documentation": {
        "overview": "<string>",
        "usage": "<string>",
        "api": "<string>",
        "troubleshooting": "<string>"
      },
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  ],
  "pagination": {
    "total": 123,
    "limit": 123,
    "offset": 123,
    "hasMore": true
  },
  "summary": {
    "totalModules": 123,
    "activeModules": 123,
    "deprecatedModules": 123,
    "betaModules": 123,
    "typeBreakdown": {},
    "categoryBreakdown": {}
  },
  "timestamp": "<string>"
}

Overview

Retrieve all available trust modules, schemas, and their configurations. This endpoint provides comprehensive information about the trust system’s capabilities, making it perfect for building trust-based applications and understanding available attestation types.
Use this endpoint to discover available trust modules, understand attestation schemas, and build applications that leverage the trust system’s capabilities.

Parameters

type
string
Filter by module type
  • schema - Attestation schemas
  • evaluator - Policy evaluators
  • verifier - Attestation verifiers
  • scorer - Trust scorers
  • all - All modules (default)
category
string
Filter by module category
  • identity - Identity-related modules
  • skill - Skill-related modules
  • relationship - Relationship modules
  • achievement - Achievement modules
  • reputation - Reputation modules
  • custom - Custom modules
status
string
Filter by module status
  • active - Active modules (default)
  • deprecated - Deprecated modules
  • beta - Beta modules
  • all - All modules
version
string
Filter by module version
limit
number
Number of modules to return (default: 50, max: 100)
offset
number
Number of modules to skip for pagination (default: 0)
includeDetails
boolean
Include detailed module information (default: true)
includeExamples
boolean
Include usage examples (default: true)

Response

success
boolean
Indicates if the request was successful
modules
array
Array of trust modules
pagination
object
Pagination information
summary
object
Module summary statistics
timestamp
string
ISO 8601 timestamp of the response

Examples

curl "https://api.onzks.com/v1/trust/modules" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "modules": [
    {
      "id": "skill_schema_v1",
      "name": "Skill Attestation Schema",
      "description": "Schema for skill and expertise attestations",
      "type": "schema",
      "category": "skill",
      "version": "1.0.0",
      "status": "active",
      "schema": {
        "fields": [
          {
            "name": "title",
            "type": "string",
            "required": true,
            "description": "Skill title",
            "validation": {
              "minLength": 1,
              "maxLength": 100
            }
          },
          {
            "name": "description",
            "type": "string",
            "required": true,
            "description": "Skill description",
            "validation": {
              "minLength": 10,
              "maxLength": 500
            }
          },
          {
            "name": "category",
            "type": "string",
            "required": true,
            "description": "Skill category",
            "validation": {
              "enum": ["programming", "design", "business", "blockchain", "other"]
            }
          },
          {
            "name": "value",
            "type": "string",
            "required": true,
            "description": "Skill level",
            "validation": {
              "enum": ["beginner", "intermediate", "advanced", "expert"]
            }
          },
          {
            "name": "metadata",
            "type": "object",
            "required": false,
            "description": "Additional metadata",
            "validation": {
              "properties": {
                "yearsExperience": {"type": "number", "minimum": 0},
                "projects": {"type": "array", "items": {"type": "string"}},
                "certifications": {"type": "array", "items": {"type": "string"}}
              }
            }
          },
          {
            "name": "evidence",
            "type": "array",
            "required": false,
            "description": "Supporting evidence",
            "validation": {
              "items": {
                "type": "object",
                "properties": {
                  "type": {"type": "string", "enum": ["url", "document", "transaction"]},
                  "value": {"type": "string"},
                  "description": {"type": "string"}
                }
              }
            }
          }
        ],
        "validation": {
          "required": ["title", "description", "category", "value"],
          "additionalProperties": false
        },
        "examples": [
          {
            "title": "Solidity Developer",
            "description": "Expert in smart contract development",
            "category": "programming",
            "value": "expert",
            "metadata": {
              "yearsExperience": 5,
              "projects": ["DeFi Protocol", "NFT Marketplace"],
              "certifications": ["Certified Solidity Developer"]
            },
            "evidence": [
              {
                "type": "url",
                "value": "https://github.com/user/solidity-projects",
                "description": "GitHub repository with Solidity projects"
              }
            ]
          }
        ]
      },
      "configuration": {
        "enabled": true,
        "settings": {
          "maxEvidenceItems": 10,
          "requireEvidence": false,
          "allowCustomFields": true
        },
        "permissions": ["create_attestation", "read_attestation"],
        "dependencies": ["identity_verification"]
      },
      "capabilities": [
        "skill_attestation",
        "evidence_validation",
        "trust_scoring",
        "reputation_building"
      ],
      "examples": [
        {
          "title": "Create Skill Attestation",
          "description": "Create a skill attestation for a developer",
          "code": "const attestation = await createAttestation({\n  subject: 'alice.zks',\n  schema: 'skill',\n  data: {\n    title: 'React Developer',\n    description: 'Expert in React and frontend development',\n    category: 'programming',\n    value: 'expert'\n  }\n});",
          "language": "javascript"
        }
      ],
      "documentation": {
        "overview": "The skill schema allows users to attest to their skills and expertise in various domains.",
        "usage": "Use this schema to create skill attestations that can be used for reputation building and trust scoring.",
        "api": "POST /v1/trust/attestations with schema: 'skill'",
        "troubleshooting": "Common issues include missing required fields and invalid evidence formats."
      },
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "relationship_schema_v1",
      "name": "Relationship Attestation Schema",
      "description": "Schema for relationship attestations",
      "type": "schema",
      "category": "relationship",
      "version": "1.0.0",
      "status": "active",
      "schema": {
        "fields": [
          {
            "name": "title",
            "type": "string",
            "required": true,
            "description": "Relationship title"
          },
          {
            "name": "description",
            "type": "string",
            "required": true,
            "description": "Relationship description"
          },
          {
            "name": "category",
            "type": "string",
            "required": true,
            "description": "Relationship category"
          },
          {
            "name": "value",
            "type": "string",
            "required": true,
            "description": "Trust level"
          }
        ],
        "validation": {
          "required": ["title", "description", "category", "value"]
        },
        "examples": [
          {
            "title": "Business Partner",
            "description": "Long-term business partnership",
            "category": "business",
            "value": "trusted"
          }
        ]
      },
      "configuration": {
        "enabled": true,
        "settings": {
          "maxRelationships": 100,
          "requireMutualConsent": true
        },
        "permissions": ["create_attestation", "read_attestation"],
        "dependencies": ["identity_verification"]
      },
      "capabilities": [
        "relationship_attestation",
        "mutual_consent",
        "trust_scoring"
      ],
      "examples": [
        {
          "title": "Create Relationship Attestation",
          "description": "Create a relationship attestation",
          "code": "const attestation = await createAttestation({\n  subject: 'bob.zks',\n  schema: 'relationship',\n  data: {\n    title: 'Business Partner',\n    description: 'Long-term business partnership',\n    category: 'business',\n    value: 'trusted'\n  }\n});",
          "language": "javascript"
        }
      ],
      "documentation": {
        "overview": "The relationship schema allows users to attest to their relationships with other users.",
        "usage": "Use this schema to create relationship attestations that can be used for trust scoring and reputation building.",
        "api": "POST /v1/trust/attestations with schema: 'relationship'",
        "troubleshooting": "Common issues include missing mutual consent and invalid relationship types."
      },
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  },
  "summary": {
    "totalModules": 25,
    "activeModules": 20,
    "deprecatedModules": 3,
    "betaModules": 2,
    "typeBreakdown": {
      "schema": 15,
      "evaluator": 5,
      "verifier": 3,
      "scorer": 2
    },
    "categoryBreakdown": {
      "skill": 8,
      "relationship": 6,
      "achievement": 4,
      "reputation": 3,
      "identity": 4
    }
  },
  "timestamp": "2024-01-20T15:45:00Z"
}

Use Cases

1. Module Discovery

Discover available trust modules:
async function discoverModules(category) {
  const modules = await getTrustModules({ category });
  
  const discovery = {
    schemas: modules.modules.filter(m => m.type === 'schema'),
    evaluators: modules.modules.filter(m => m.type === 'evaluator'),
    verifiers: modules.modules.filter(m => m.type === 'verifier'),
    scorers: modules.modules.filter(m => m.type === 'scorer')
  };
  
  return discovery;
}

// Usage
const skillModules = await discoverModules('skill');
console.log('Available skill schemas:', skillModules.schemas.length);

2. Schema Validation

Validate attestation data against schemas:
function validateAttestationData(schema, data) {
  const validation = {
    valid: true,
    errors: [],
    warnings: []
  };
  
  // Check required fields
  schema.schema.fields.forEach(field => {
    if (field.required && !data[field.name]) {
      validation.valid = false;
      validation.errors.push(`Missing required field: ${field.name}`);
    }
  });
  
  // Check field types
  schema.schema.fields.forEach(field => {
    if (data[field.name] && typeof data[field.name] !== field.type) {
      validation.valid = false;
      validation.errors.push(`Invalid type for field ${field.name}: expected ${field.type}`);
    }
  });
  
  return validation;
}

3. Module Configuration

Configure modules for your application:
async function configureModules(moduleIds, settings) {
  const configurations = [];
  
  for (const moduleId of moduleIds) {
    const module = await getTrustModules({ id: moduleId });
    
    const configuration = {
      moduleId,
      enabled: settings[moduleId]?.enabled || true,
      settings: {
        ...module.configuration.settings,
        ...settings[moduleId]?.settings
      }
    };
    
    configurations.push(configuration);
  }
  
  return configurations;
}

4. Module Dependencies

Resolve module dependencies:
function resolveDependencies(modules) {
  const resolved = [];
  const unresolved = [...modules];
  
  while (unresolved.length > 0) {
    const module = unresolved.shift();
    
    if (module.configuration.dependencies.every(dep => 
      resolved.some(m => m.id === dep)
    )) {
      resolved.push(module);
    } else {
      unresolved.push(module);
    }
  }
  
  return resolved;
}

5. Module Testing

Test modules before deployment:
async function testModule(module, testData) {
  const tests = [];
  
  // Test schema validation
  if (module.type === 'schema') {
    const validation = validateAttestationData(module, testData);
    tests.push({
      name: 'Schema Validation',
      passed: validation.valid,
      errors: validation.errors
    });
  }
  
  // Test module functionality
  if (module.capabilities.includes('trust_scoring')) {
    const score = await testTrustScoring(module, testData);
    tests.push({
      name: 'Trust Scoring',
      passed: score > 0,
      score
    });
  }
  
  return tests;
}

Best Practices

1. Module Selection

Choose appropriate modules:
function selectModules(requirements) {
  const modules = await getTrustModules();
  
  const selected = modules.modules.filter(module => {
    return requirements.every(req => 
      module.capabilities.includes(req) || 
      module.category === req
    );
  });
  
  return selected;
}

2. Version Management

Manage module versions:
function getLatestVersions(modules) {
  const latest = {};
  
  modules.forEach(module => {
    if (!latest[module.id] || 
        compareVersions(module.version, latest[module.id].version) > 0) {
      latest[module.id] = module;
    }
  });
  
  return Object.values(latest);
}

3. Caching

Cache module data:
let moduleCache = new Map();
const CACHE_TTL = 60 * 60 * 1000; // 1 hour

async function getCachedModules(options = {}) {
  const cacheKey = JSON.stringify(options);
  const cached = moduleCache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await getTrustModules(options);
  moduleCache.set(cacheKey, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}

4. Documentation

Generate module documentation:
function generateModuleDocs(module) {
  return {
    title: module.name,
    description: module.description,
    usage: module.documentation.usage,
    examples: module.examples,
    api: module.documentation.api,
    troubleshooting: module.documentation.troubleshooting
  };
}

Troubleshooting

”No modules found”

Cause: No modules match the criteria or invalid filters. Solution:
  • Remove restrictive filters
  • Check if modules exist
  • Verify filter values are correct

”Invalid module type”

Cause: Unsupported module type. Solution:
  • Use supported types: schema, evaluator, verifier, scorer, all
  • Check for typos

”Invalid category”

Cause: Unsupported category value. Solution:
  • Use supported categories: identity, skill, relationship, achievement, reputation, custom
  • Check for typos

Rate Limits

Module requests are subject to rate limits:
  • Free tier: 60 requests per minute
  • Starter tier: 300 requests per minute
  • Professional tier: 1,000 requests per minute
  • Enterprise tier: Custom limits
Implement caching to reduce API calls.