Evaluate Policy - ZKScore Documentation

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>"
}

POST

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

Show policy properties

policy.id

string

Unique policy identifier

policy.name

string

Policy name

policy.description

string

Policy description

policy.requirements

array

Policy requirements

Show requirement properties

policy.requirements[].type

string

Requirement type (trustScore, attestation, skill, relationship, etc.)

policy.requirements[].operator

string

Comparison operator (gte, lte, eq, in, contains, etc.)

policy.requirements[].value

any

Requirement value

policy.requirements[].weight

number

Requirement weight (0-1)

policy.requirements[].required

boolean

Whether requirement is mandatory

policy.conditions

array

Policy conditions

Show condition properties

policy.conditions[].type

string

Condition type (and, or, not)

policy.conditions[].requirements

array

Requirements to evaluate

policy.threshold

number

Minimum score threshold (0-100)

policy.expiry

string

Policy expiry date (ISO 8601)

subject

string

required

Subject identity to evaluate (ZKS ID or wallet address)

context

object

Additional context for evaluation

Show context properties

context.service

string

Service requesting evaluation

context.action

string

Action being evaluated

context.metadata

object

Additional metadata

options

object

Evaluation options

Show options properties

options.includeDetails

boolean

Include detailed evaluation results (default: true)

options.includeAttestations

boolean

Include relevant attestations (default: true)

options.includeScore

boolean

Include trust score breakdown (default: true)

options.strictMode

boolean

Use strict evaluation mode (default: false)

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

Show policy properties

string

Policy identifier

name

string

Policy name

description

string

Policy description

requirements

array

Requirement evaluation results

Show requirement properties

type

string

Requirement type

passed

boolean

Whether requirement passed

score

number

Requirement score

weight

number

Requirement weight

required

boolean

Whether requirement is mandatory

details

object

Requirement evaluation details

attestations

array

Relevant attestations used in evaluation

Show attestation properties

string

Attestation identifier

schema

string

Attestation schema

trustScore

number

Attestation trust score

relevance

number

Relevance to policy (0-1)

breakdown

object

Score breakdown by category

Show breakdown properties

trustScore

number

Overall trust score

attestationScore

number

Attestation-based score

skillScore

number

Skill-based score

relationshipScore

number

Relationship-based score

achievementScore

number

Achievement-based score

recommendations

array

Recommendations for improvement

Show recommendation properties

type

string

Recommendation type

description

string

Recommendation description

impact

number

Expected impact on score

priority

string

Recommendation priority (high, medium, low)

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;
}

Get Attestations - Retrieve attestations
Create Attestation - Create new attestations
Revoke Attestation - Revoke attestations
Get Modules - Get available trust modules

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.

Revoke Attestation Create API Key

​Overview

​Parameters

​Response

​Examples

​Response Example

​Use Cases

​1. Access Control

​2. Credential Verification

​3. Service Eligibility

​4. Policy Testing

​5. Policy Optimization

​Best Practices

​1. Policy Design

​2. Caching

​3. Error Handling

​4. Monitoring

​Related Endpoints

​Troubleshooting

​”Policy not found”

​”Subject not found”

​”Invalid policy format”

​”Evaluation failed”

​Rate Limits

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. Access Control

2. Credential Verification

3. Service Eligibility

4. Policy Testing

5. Policy Optimization

Best Practices

1. Policy Design

2. Caching

3. Error Handling

4. Monitoring

Related Endpoints

Troubleshooting

”Policy not found”

”Subject not found”

”Invalid policy format”

”Evaluation failed”

Rate Limits