Create Attestation

Overview

Create a new trust attestation that provides verifiable proof of a relationship, skill, or attribute. This endpoint allows users to issue attestations that can be used for trust scoring, reputation building, and identity verification.

Use this endpoint to create verifiable attestations that can be used for trust scoring, reputation systems, and identity verification. Attestations are cryptographically signed and immutable.

Parameters

subject

string

required

The identity being attested to (ZKS ID or wallet address)

schema

string

required

The attestation schema identifier

skill - Skill or expertise attestation
relationship - Relationship attestation
achievement - Achievement attestation
reputation - Reputation attestation
identity - Identity verification attestation
custom - Custom schema

data

object

required

Attestation data payload

Show data properties

data.title

string

Attestation title

data.description

string

Attestation description

data.category

string

Attestation category

data.value

string

Attestation value or score

data.metadata

object

Additional metadata

data.evidence

array

Supporting evidence

Show evidence properties

data.evidence[].type

string

Evidence type (url, document, transaction, etc.)

data.evidence[].value

string

Evidence value

data.evidence[].description

string

Evidence description

signature

string

required

Cryptographic signature of the attestation

expiry

string

ISO 8601 timestamp when attestation expires (optional)

revocable

boolean

Whether the attestation can be revoked (default: true)

public

boolean

Whether the attestation is publicly visible (default: true)

Response

success

boolean

Indicates if the attestation was created successfully

attestationId

string

Unique identifier of the created attestation

attestation

object

Created attestation details

Show attestation properties

string

Attestation identifier

subject

string

Attested identity

issuer

string

Attestation issuer

schema

string

Attestation schema

data

object

Attestation data

signature

string

Attestation signature

createdAt

string

ISO 8601 timestamp of creation

expiry

string

ISO 8601 timestamp of expiry (if set)

revocable

boolean

Whether attestation can be revoked

public

boolean

Whether attestation is publicly visible

status

string

Attestation status (active, expired, revoked)

Examples

curl -X POST "https://api.onzks.com/v1/trust/attestations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "alice.zks",
    "schema": "skill",
    "data": {
      "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/alice/solidity-projects",
          "description": "GitHub repository with Solidity projects"
        },
        {
          "type": "document",
          "value": "certificate.pdf",
          "description": "Certification document"
        }
      ]
    },
    "signature": "0xabcdef1234567890...",
    "expiry": "2025-01-20T15:45:00Z",
    "revocable": true,
    "public": true,
    "tags": ["solidity", "blockchain", "developer"]
  }'

Response Example

{
  "success": true,
  "attestationId": "att_1234567890abcdef",
  "attestation": {
    "id": "att_1234567890abcdef",
    "subject": "alice.zks",
    "issuer": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "schema": "skill",
    "data": {
      "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/alice/solidity-projects",
          "description": "GitHub repository with Solidity projects"
        },
        {
          "type": "document",
          "value": "certificate.pdf",
          "description": "Certification document"
        }
      ]
    },
    "signature": "0xabcdef1234567890...",
    "createdAt": "2024-01-20T15:45:00Z",
    "expiry": "2025-01-20T15:45:00Z",
    "revocable": true,
    "public": true,
    "status": "active",
    "tags": ["solidity", "blockchain", "developer"]
  },
  "verification": {
    "verified": true,
    "verificationMethod": "signature_verification",
    "verificationTimestamp": "2024-01-20T15:45:00Z",
    "trustScore": 85.5
  },
  "timestamp": "2024-01-20T15:45:00Z"
}

Use Cases

1. Skill Attestation System

Create a skill attestation system:

async function createSkillAttestation(subject, skill, evidence) {
  const attestationData = {
    subject,
    schema: 'skill',
    data: {
      title: skill.name,
      description: skill.description,
      category: skill.category,
      value: skill.level,
      metadata: {
        yearsExperience: skill.experience,
        projects: skill.projects,
        certifications: skill.certifications
      },
      evidence: evidence.map(ev => ({
        type: ev.type,
        value: ev.value,
        description: ev.description
      }))
    },
    signature: await signAttestation(subject, skill),
    tags: skill.tags
  };

  return await createAttestation(attestationData);
}

// Usage
const skill = {
  name: 'React Developer',
  description: 'Expert in React and frontend development',
  category: 'programming',
  level: 'expert',
  experience: 3,
  projects: ['E-commerce Platform', 'Dashboard App'],
  certifications: ['React Certification'],
  tags: ['react', 'javascript', 'frontend']
};

const evidence = [
  {
    type: 'url',
    value: 'https://github.com/alice/react-projects',
    description: 'GitHub repository with React projects'
  }
];

await createSkillAttestation('alice.zks', skill, evidence);

2. Relationship Attestation

Create relationship attestations:

async function createRelationshipAttestation(subject, relationship) {
  const attestationData = {
    subject,
    schema: 'relationship',
    data: {
      title: relationship.title,
      description: relationship.description,
      category: relationship.category,
      value: relationship.trustLevel,
      metadata: {
        relationshipType: relationship.type,
        duration: relationship.duration,
        projects: relationship.projects
      },
      evidence: relationship.evidence
    },
    signature: await signAttestation(subject, relationship),
    tags: relationship.tags
  };

  return await createAttestation(attestationData);
}

// Usage
const relationship = {
  title: 'Business Partner',
  description: 'Long-term business partnership',
  category: 'business',
  trustLevel: 'trusted',
  type: 'business_partner',
  duration: '3 years',
  projects: ['Joint Venture', 'Consulting'],
  evidence: [
    {
      type: 'transaction',
      value: '0x1234567890abcdef...',
      description: 'Business transaction history'
    }
  ],
  tags: ['business', 'partnership', 'trusted']
};

await createRelationshipAttestation('bob.zks', relationship);

3. Achievement Attestation

Create achievement attestations:

async function createAchievementAttestation(subject, achievement) {
  const attestationData = {
    subject,
    schema: 'achievement',
    data: {
      title: achievement.title,
      description: achievement.description,
      category: achievement.category,
      value: achievement.status,
      metadata: {
        completionDate: achievement.completionDate,
        metrics: achievement.metrics,
        impact: achievement.impact
      },
      evidence: achievement.evidence
    },
    signature: await signAttestation(subject, achievement),
    revocable: false, // Achievements are typically not revocable
    tags: achievement.tags
  };

  return await createAttestation(attestationData);
}

// Usage
const achievement = {
  title: 'DeFi Protocol Launch',
  description: 'Successfully launched a DeFi protocol',
  category: 'achievement',
  status: 'completed',
  completionDate: '2024-01-15',
  metrics: {
    totalValueLocked: '1000000',
    users: 500,
    transactions: 10000
  },
  impact: 'High',
  evidence: [
    {
      type: 'url',
      value: 'https://yieldfarm.xyz',
      description: 'Protocol website'
    },
    {
      type: 'transaction',
      value: '0xabcdef1234567890...',
      description: 'Protocol deployment transaction'
    }
  ],
  tags: ['defi', 'protocol', 'launch', 'achievement']
};

await createAchievementAttestation('charlie.zks', achievement);

4. Batch Attestation Creation

Create multiple attestations at once:

async function createBatchAttestations(attestations) {
  const results = [];
  
  for (const attestation of attestations) {
    try {
      const result = await createAttestation(attestation);
      results.push({ success: true, result });
    } catch (error) {
      results.push({ success: false, error: error.message });
    }
  }
  
  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);
  
  console.log(`Successfully created ${successful.length} attestations`);
  if (failed.length > 0) {
    console.log(`Failed to create ${failed.length} attestations`);
  }
  
  return results;
}

5. Attestation Templates

Use predefined templates:

const attestationTemplates = {
  skill: {
    schema: 'skill',
    requiredFields: ['title', 'description', 'category', 'value'],
    optionalFields: ['metadata', 'evidence'],
    defaultTags: ['skill', 'attestation']
  },
  relationship: {
    schema: 'relationship',
    requiredFields: ['title', 'description', 'category', 'value'],
    optionalFields: ['metadata', 'evidence'],
    defaultTags: ['relationship', 'attestation']
  },
  achievement: {
    schema: 'achievement',
    requiredFields: ['title', 'description', 'category', 'value'],
    optionalFields: ['metadata', 'evidence'],
    defaultTags: ['achievement', 'attestation']
  }
};

function createAttestationFromTemplate(template, data) {
  const templateConfig = attestationTemplates[template];
  
  if (!templateConfig) {
    throw new Error(`Unknown template: ${template}`);
  }
  
  // Validate required fields
  for (const field of templateConfig.requiredFields) {
    if (!data[field]) {
      throw new Error(`Missing required field: ${field}`);
    }
  }
  
  return {
    schema: templateConfig.schema,
    data: {
      ...data,
      tags: [...(data.tags || []), ...templateConfig.defaultTags]
    }
  };
}

Best Practices

1. Signature Verification

Always verify signatures before creating attestations:

async function verifyAttestationSignature(attestation, signature) {
  const message = JSON.stringify(attestation);
  const recoveredAddress = await recoverAddress(message, signature);
  
  return recoveredAddress === attestation.issuer;
}

2. Evidence Validation

Validate evidence before creating attestations:

function validateEvidence(evidence) {
  const validTypes = ['url', 'document', 'transaction', 'image', 'video'];
  
  return evidence.every(ev => {
    return validTypes.includes(ev.type) && 
           ev.value && 
           ev.description;
  });
}

3. Expiry Management

Handle attestation expiry:

function checkAttestationExpiry(attestation) {
  if (!attestation.expiry) {
    return { expired: false, daysRemaining: null };
  }
  
  const expiryDate = new Date(attestation.expiry);
  const now = new Date();
  const daysRemaining = Math.ceil((expiryDate - now) / (1000 * 60 * 60 * 24));
  
  return {
    expired: now > expiryDate,
    daysRemaining: daysRemaining > 0 ? daysRemaining : 0
  };
}

4. Privacy Controls

Implement privacy controls:

function createPrivateAttestation(attestationData) {
  return {
    ...attestationData,
    public: false,
    tags: [...(attestationData.tags || []), 'private']
  };
}

function createPublicAttestation(attestationData) {
  return {
    ...attestationData,
    public: true,
    tags: [...(attestationData.tags || []), 'public']
  };
}

Get Attestations - Retrieve attestations
Revoke Attestation - Revoke an attestation
Evaluate Policy - Evaluate trust policies
Get Modules - Get available trust modules

Troubleshooting

”Invalid signature”

Cause: The signature doesn’t match the attestation data. Solution:

Verify the signature is correctly generated
Ensure the message being signed matches the attestation data
Check that the correct private key is being used

”Invalid schema”

Cause: Unsupported schema identifier. Solution:

Use supported schemas: skill, relationship, achievement, reputation, identity, custom
Check for typos in the schema name

”Missing required fields”

Cause: Required fields are missing from the attestation data. Solution:

Include all required fields for the schema
Check the schema documentation for required fields
Validate the data structure before submission

”Attestation already exists”

Cause: An identical attestation already exists. Solution:

Check if the attestation already exists
Modify the attestation data to make it unique
Consider updating the existing attestation instead

Rate Limits

Attestation creation requests are subject to rate limits:

Free tier: 10 attestations per minute
Starter tier: 50 attestations per minute
Professional tier: 200 attestations per minute
Enterprise tier: Custom limits

Implement queuing for batch attestation creation to avoid rate limits.

API Documentation

Identity

Scores

Achievements

Trading

Trust Layer

Developer Tools

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. Skill Attestation System

2. Relationship Attestation

3. Achievement Attestation

4. Batch Attestation Creation

5. Attestation Templates

Best Practices

1. Signature Verification

2. Evidence Validation

3. Expiry Management

4. Privacy Controls

Troubleshooting

”Invalid signature”

”Invalid schema”

”Missing required fields”

”Attestation already exists”

Rate Limits

API Documentation

Identity

Scores

Achievements

Trading

Trust Layer

Developer Tools

Documentation Index

​Overview

​Parameters

​Response

​Examples

​Response Example

​Use Cases

​1. Skill Attestation System

​2. Relationship Attestation

​3. Achievement Attestation

​4. Batch Attestation Creation

​5. Attestation Templates

​Best Practices

​1. Signature Verification

​2. Evidence Validation

​3. Expiry Management

​4. Privacy Controls

​Related Endpoints

​Troubleshooting

​”Invalid signature”

​”Invalid schema”

​”Missing required fields”

​”Attestation already exists”

​Rate Limits

Overview

Parameters

Response

Examples

Response Example

Use Cases

1. Skill Attestation System

2. Relationship Attestation

3. Achievement Attestation

4. Batch Attestation Creation

5. Attestation Templates

Best Practices

1. Signature Verification

2. Evidence Validation

3. Expiry Management

4. Privacy Controls

Related Endpoints

Troubleshooting

”Invalid signature”

”Invalid schema”

”Missing required fields”

”Attestation already exists”

Rate Limits