Skip to main content
POST
https://api-mainnet.onzks.com
/
v1
/
trust
/
evaluate
Evaluate Policy
curl --request POST \
  --url https://api-mainnet.onzks.com/v1/trust/evaluate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "policy": {
    "policy.id": "<string>",
    "policy.name": "<string>",
    "policy.description": "<string>",
    "policy.requirements": [
      {
        "policy.requirements[].type": "<string>",
        "policy.requirements[].operator": "<string>",
        "policy.requirements[].value": "<any>",
        "policy.requirements[].weight": 123,
        "policy.requirements[].required": true
      }
    ],
    "policy.conditions": [
      {
        "policy.conditions[].type": "<string>",
        "policy.conditions[].requirements": [
          {}
        ]
      }
    ],
    "policy.threshold": 123,
    "policy.expiry": "<string>"
  },
  "subject": "<string>",
  "context": {
    "context.service": "<string>",
    "context.action": "<string>",
    "context.metadata": {}
  },
  "options": {
    "options.includeDetails": true,
    "options.includeAttestations": true,
    "options.includeScore": true,
    "options.strictMode": true
  }
}
'
{
  "success": true,
  "passed": true,
  "score": 123,
  "threshold": 123,
  "subject": "<string>",
  "policy": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>"
  },
  "requirements": [
    {
      "type": "<string>",
      "passed": true,
      "score": 123,
      "weight": 123,
      "required": true,
      "details": {}
    }
  ],
  "attestations": [
    {
      "id": "<string>",
      "schema": "<string>",
      "trustScore": 123,
      "relevance": 123
    }
  ],
  "breakdown": {
    "trustScore": 123,
    "attestationScore": 123,
    "skillScore": 123,
    "relationshipScore": 123,
    "achievementScore": 123
  },
  "recommendations": [
    {
      "type": "<string>",
      "description": "<string>",
      "impact": 123,
      "priority": "<string>"
    }
  ],
  "timestamp": "<string>"
}

​
Overview

Evaluate trust policies to determine if a subject meets specific trust requirements. This endpoint allows you to check compliance with trust-based access control, verify credentials, and assess eligibility for services based on trust scores and attestations.
Use this endpoint to implement trust-based access control, verify user credentials, and assess eligibility for services based on trust requirements.

​
Parameters

​
policy
object
required
Trust policy to evaluate
​
subject
string
required
Subject identity to evaluate (ZKS ID or wallet address)
​
context
object
Additional context for evaluation
​
options
object
Evaluation options

​
Response

​
success
boolean
Indicates if the evaluation was successful
​
passed
boolean
Whether the subject passed the policy evaluation
​
score
number
Overall evaluation score (0-100)
​
threshold
number
Policy threshold score
​
subject
string
Evaluated subject identity
​
policy
object
Policy details
​
requirements
array
Requirement evaluation results
​
attestations
array
Relevant attestations used in evaluation
​
breakdown
object
Score breakdown by category
​
recommendations
array
Recommendations for improvement
​
timestamp
string
ISO 8601 timestamp of the evaluation

​
Examples

curl -X POST "https://api.onzks.com/v1/trust/evaluate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "id": "defi_access_policy",
      "name": "DeFi Protocol Access",
      "description": "Access policy for DeFi protocols",
      "requirements": [
        {
          "type": "trustScore",
          "operator": "gte",
          "value": 70,
          "weight": 0.4,
          "required": true
        },
        {
          "type": "attestation",
          "operator": "contains",
          "value": "skill",
          "weight": 0.3,
          "required": true
        },
        {
          "type": "attestation",
          "operator": "contains",
          "value": "relationship",
          "weight": 0.3,
          "required": false
        }
      ],
      "threshold": 75
    },
    "subject": "alice.zks",
    "context": {
      "service": "defi_protocol",
      "action": "lending"
    }
  }'

​
Response Example

{
  "success": true,
  "passed": true,
  "score": 82.5,
  "threshold": 75,
  "subject": "alice.zks",
  "policy": {
    "id": "defi_access_policy",
    "name": "DeFi Protocol Access",
    "description": "Access policy for DeFi protocols"
  },
  "requirements": [
    {
      "type": "trustScore",
      "passed": true,
      "score": 85.0,
      "weight": 0.4,
      "required": true,
      "details": {
        "currentScore": 85.0,
        "requiredScore": 70.0,
        "difference": 15.0
      }
    },
    {
      "type": "attestation",
      "passed": true,
      "score": 90.0,
      "weight": 0.3,
      "required": true,
      "details": {
        "schema": "skill",
        "count": 3,
        "averageTrustScore": 90.0
      }
    },
    {
      "type": "attestation",
      "passed": true,
      "score": 75.0,
      "weight": 0.3,
      "required": false,
      "details": {
        "schema": "relationship",
        "count": 2,
        "averageTrustScore": 75.0
      }
    }
  ],
  "attestations": [
    {
      "id": "att_1234567890abcdef",
      "schema": "skill",
      "trustScore": 90.0,
      "relevance": 0.9
    },
    {
      "id": "att_abcdef1234567890",
      "schema": "relationship",
      "trustScore": 75.0,
      "relevance": 0.7
    }
  ],
  "breakdown": {
    "trustScore": 85.0,
    "attestationScore": 82.5,
    "skillScore": 90.0,
    "relationshipScore": 75.0,
    "achievementScore": 0.0
  },
  "recommendations": [
    {
      "type": "improvement",
      "description": "Consider adding more relationship attestations to improve your score",
      "impact": 5.0,
      "priority": "medium"
    },
    {
      "type": "maintenance",
      "description": "Your current score is good, maintain your existing attestations",
      "impact": 0.0,
      "priority": "low"
    }
  ],
  "timestamp": "2024-01-20T15:45:00Z"
}

​
Use Cases

​
1. Access Control

Implement trust-based access control: 
async function checkAccess(subject, service, action) {
  const policy = await getAccessPolicy(service, action);
  
  const result = await evaluatePolicy(policy, subject, {
    service,
    action
  });
  
  return {
    allowed: result.passed,
    score: result.score,
    threshold: result.threshold,
    requirements: result.requirements,
    recommendations: result.recommendations
  };
}

// Usage
const access = await checkAccess('alice.zks', 'defi_protocol', 'lending');
if (access.allowed) {
  console.log('Access granted');
} else {
  console.log('Access denied. Recommendations:', access.recommendations);
}

​
2. Credential Verification

Verify user credentials: 
async function verifyCredentials(subject, requiredCredentials) {
  const policy = {
    id: 'credential_verification',
    name: 'Credential Verification',
    description: 'Verify required credentials',
    requirements: requiredCredentials.map(cred => ({
      type: 'attestation',
      operator: 'contains',
      value: cred.schema,
      weight: cred.weight || 1.0,
      required: cred.required !== false
    })),
    threshold: 80
  };
  
  return await evaluatePolicy(policy, subject);
}

// Usage
const credentials = [
  { schema: 'skill', weight: 0.4, required: true },
  { schema: 'identity', weight: 0.3, required: true },
  { schema: 'reputation', weight: 0.3, required: false }
];

const verification = await verifyCredentials('alice.zks', credentials);

​
3. Service Eligibility

Check eligibility for services: 
async function checkEligibility(subject, service) {
  const policies = await getServicePolicies(service);
  
  const results = await Promise.all(
    policies.map(policy => evaluatePolicy(policy, subject))
  );
  
  const overallPassed = results.every(result => result.passed);
  const averageScore = results.reduce((sum, result) => sum + result.score, 0) / results.length;
  
  return {
    eligible: overallPassed,
    averageScore,
    results,
    recommendations: results.flatMap(r => r.recommendations)
  };
}

​
4. Policy Testing

Test policies before deployment: 
async function testPolicy(policy, testSubjects) {
  const results = await Promise.all(
    testSubjects.map(subject => evaluatePolicy(policy, subject))
  );
  
  const analysis = {
    totalTests: results.length,
    passed: results.filter(r => r.passed).length,
    failed: results.filter(r => !r.passed).length,
    averageScore: results.reduce((sum, r) => sum + r.score, 0) / results.length,
    scoreDistribution: analyzeScoreDistribution(results),
    commonFailures: identifyCommonFailures(results)
  };
  
  return analysis;
}

​
5. Policy Optimization

Optimize policies based on results: 
function optimizePolicy(policy, evaluationResults) {
  const failedRequirements = evaluationResults
    .filter(r => !r.passed)
    .flatMap(r => r.requirements.filter(req => !req.passed));
  
  const optimization = {
    adjustThreshold: calculateThresholdAdjustment(failedRequirements),
    modifyRequirements: suggestRequirementChanges(failedRequirements),
    addRequirements: suggestNewRequirements(evaluationResults),
    removeRequirements: suggestRequirementRemoval(failedRequirements)
  };
  
  return optimization;
}

​
Best Practices

​
1. Policy Design

Design effective policies: 
function createEffectivePolicy(requirements, threshold) {
  return {
    id: generatePolicyId(),
    name: 'Effective Policy',
    description: 'Well-designed policy',
    requirements: requirements.map(req => ({
      ...req,
      weight: req.weight || 1.0,
      required: req.required !== false
    })),
    threshold: threshold || 70,
    conditions: createLogicalConditions(requirements)
  };
}

​
2. Caching

Cache policy evaluations: 
let policyCache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedPolicyEvaluation(policy, subject) {
  const cacheKey = `${policy.id}-${subject}`;
  const cached = policyCache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await evaluatePolicy(policy, subject);
  policyCache.set(cacheKey, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}

​
3. Error Handling

Handle evaluation errors: 
async function safeEvaluatePolicy(policy, subject) {
  try {
    return await evaluatePolicy(policy, subject);
  } catch (error) {
    if (error.message.includes('Policy not found')) {
      throw new Error('Invalid policy');
    } else if (error.message.includes('Subject not found')) {
      throw new Error('Invalid subject');
    } else {
      throw new Error('Evaluation failed');
    }
  }
}

​
4. Monitoring

Monitor policy performance: 
function monitorPolicyPerformance(policy, evaluations) {
  const metrics = {
    totalEvaluations: evaluations.length,
    passRate: evaluations.filter(e => e.passed).length / evaluations.length,
    averageScore: evaluations.reduce((sum, e) => sum + e.score, 0) / evaluations.length,
    commonFailures: identifyCommonFailures(evaluations),
    performanceTrends: analyzePerformanceTrends(evaluations)
  };
  
  return metrics;
}

​
Troubleshooting

​
”Policy not found”

Cause: Invalid policy ID or policy doesn’t exist. Solution:
  • Verify the policy ID is correct
  • Check if the policy exists
  • Ensure you have access to the policy

​
”Subject not found”

Cause: Invalid subject identity or subject doesn’t exist. Solution:
  • Verify the subject identity is correct
  • Check if the subject exists
  • Ensure the subject has some activity

​
”Invalid policy format”

Cause: Policy structure is invalid. Solution:
  • Check the policy structure
  • Ensure all required fields are present
  • Validate the policy format

​
”Evaluation failed”

Cause: Internal error during evaluation. Solution:
  • Check the policy requirements
  • Verify the subject data
  • Contact support if the issue persists

​
Rate Limits

Policy evaluation 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.