Claims Management

The Claims module enables the creation, processing, and management of verifiable claims on IXO Protocol blockchains, with cryptographic proofs, verification workflows, and payment automations.

Overview

The Claims module provides:

Verifiable claim creation and management
Automated verification workflows
Multi-party evaluation processes
Dispute resolution mechanisms
Cryptographic proof generation
Payment automations with governance-controlled fees

Claim Structure

interface Claim {
  id: string;              // Unique identifier
  type: string;           // Claim type
  issuer: string;         // Issuer DID
  subject: string;        // Subject DID
  data: any;             // Claim data
  proof: string;         // Cryptographic proof
}

interface ClaimVerification {
  id: string;             // Verification ID
  type: string;          // Verification type
  method: string;        // Verification method
  verifier: string;      // Verifier DID
  status: string;        // Verification status
  proof: string;        // Verification proof
}

Claim Collections

Claim Collections enable grouping of related claims for efficient management, batch processing, and aggregated verification.

interface ClaimCollection {
  id: string;              // Collection identifier
  name: string;           // Collection name
  type: string;          // Collection type
  owner: string;         // Owner DID
  claims: string[];      // Claim IDs
  metadata: {
    description?: string;
    schema?: string;
    version?: string;
  };
}

async function createCollection(
  creator: string,
  collectionData: Partial<ClaimCollection>
) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgCreateCollection",
    value: {
      creator,
      name: collectionData.name,
      type: collectionData.type,
      metadata: collectionData.metadata
    }
  };
  
  return await Claims.broadcast(msg);
}

async function addClaimToCollection(
  collectionId: string,
  claimId: string
) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgAddClaimToCollection",
    value: {
      collectionId,
      claimId
    }
  };
  
  return await Claims.broadcast(msg);
}

async function batchVerifyClaims(
  collectionId: string,
  verifier: string,
  status: "approved" | "rejected"
) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgBatchEvaluateClaims",
    value: {
      collectionId,
      verifier,
      status
    }
  };
  
  return await Claims.broadcast(msg);
}

async function queryCollection(
  collectionId: string
) {
  const query = `
    query GetCollection($id: String!) {
      collection(id: $id) {
        id
        name
        type
        claims {
          id
          status
          evaluations {
            status
            verifier
          }
        }
        metadata
      }
    }
  `;

  return await client.query({
    query,
    variables: { id: collectionId }
  });
}

Agent Authorization

Agents can be authorized to submit, process, and evaluate claims through role-based permissions and verifiable credentials.

interface AgentRole {
  id: string;              // Role identifier
  type: "evaluator" | "processor" | "resolver";
  capabilities: string[];  // Allowed actions
  constraints: {
    claimTypes: string[];  // Authorized claim types
    collections?: string[]; // Specific collections
    timeLimit?: number;    // Role duration in blocks
  };
}

async function authorizeAgent(
  agentDid: string,
  role: AgentRole,
  authorization: {
    authorizerId: string;
    credential: VerifiableCredential;
  }
) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgAuthorizeAgent",
    value: {
      agentDid,
      role,
      authorization
    }
  };
  
  return await Claims.broadcast(msg);
}

interface AgentCredential {
  type: "ClaimEvaluator" | "ClaimProcessor" | "DisputeResolver";
  issuer: string;
  subject: string;
  capabilities: {
    actions: string[];
    conditions: {
      claimTypes: string[];
      startDate: string;
      endDate?: string;
    };
  };
}

async function issueAgentCredential(
  params: {
    type: AgentCredential["type"];
    subject: string;
    capabilities: AgentCredential["capabilities"];
  }
) {
  const credential = await Claims.createVerifiableCredential({
    type: params.type,
    issuer: getIssuerDid(),
    subject: params.subject,
    claims: {
      capabilities: params.capabilities
    }
  });

  return credential;
}

interface AgentPermissions {
  did: string;
  roles: AgentRole[];
  credentials: VerifiableCredential[];
  status: "active" | "suspended" | "revoked";
}

async function updateAgentPermissions(
  agentDid: string,
  updates: Partial<AgentPermissions>
) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgUpdateAgentPermissions",
    value: {
      agentDid,
      ...updates
    }
  };
  
  return await Claims.broadcast(msg);
}

async function revokeAgentAuthorization(
  agentDid: string,
  roleId: string,
  reason: string
) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgRevokeAgentAuthorization",
    value: {
      agentDid,
      roleId,
      reason
    }
  };
  
  return await Claims.broadcast(msg);
}

Define Agent Role
- Specify role type
- Set capabilities
- Define constraints
- Configure time limits
Issue Credentials
- Create verifiable credential
- Define capabilities
- Set validity period
- Sign by authorizer
Authorize Agent
- Assign role
- Grant permissions
- Link credentials
- Activate authorization
Monitor & Manage
- Track agent activity
- Review performance
- Update permissions
- Handle revocations

Role Configuration

Define clear responsibilities
Set appropriate constraints
Implement time limits
Regular role reviews

Credential Management

Use strong verification
Include expiration dates
Regular credential rotation
Maintain credential chain

Access Control

Implement least privilege
Regular access reviews
Monitor agent actions
Quick revocation process

Claim Evaluation & Disputes

Claims go through a structured evaluation process with support for multi-party verification and dispute resolution.

interface EvaluationParams {
  claimId: string;
  evaluator: string;
  status: "approved" | "rejected" | "disputed";
  evidence?: {
    type: string;
    data: any;
    proof: string;
  };
  reason?: string;
}

async function evaluateClaim(params: EvaluationParams) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgEvaluateClaim",
    value: {
      claimId: params.claimId,
      evaluator: params.evaluator,
      status: params.status,
      evidence: params.evidence,
      reason: params.reason
    }
  };
  
  return await Claims.broadcast(msg);
}

interface DisputeParams {
  claimId: string;
  disputerId: string;
  evaluationId: string;
  reason: string;
  evidence: {
    type: string;
    data: any;
    proof: string;
  };
}

async function submitDispute(params: DisputeParams) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgSubmitDispute",
    value: {
      claimId: params.claimId,
      disputerId: params.disputerId,
      evaluationId: params.evaluationId,
      reason: params.reason,
      evidence: params.evidence
    }
  };
  
  return await Claims.broadcast(msg);
}

async function resolveDispute(
  disputeId: string,
  resolverId: string,
  resolution: "upheld" | "rejected",
  reason: string
) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgResolveDispute",
    value: {
      disputeId,
      resolverId,
      resolution,
      reason
    }
  };
  
  return await Claims.broadcast(msg);
}

interface VerificationPolicy {
  threshold: number;        // Required approvals
  evaluators: string[];     // Authorized evaluators
  timeout: number;         // Evaluation timeout in blocks
  disputeWindow: number;   // Blocks to allow disputes
}

async function setVerificationPolicy(
  claimType: string,
  policy: VerificationPolicy
) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgSetVerificationPolicy",
    value: {
      claimType,
      policy
    }
  };
  
  return await Claims.broadcast(msg);
}

Payment Automations

The Claims module supports automated payment processing with network-governed fee distributions. All fee percentages for platform, network DAO, and evaluators are set through governance proposals.

interface CollectionPaymentConfig {
  enabled: boolean;
  tokens: {
    type: "native" | "ibc" | "cw20";  // Token type
    denom: string;                    // Token denomination
    minAmount: string;               // Minimum payment amount
    maxAmount?: string;             // Optional maximum amount
  }[];
}

async function setCollectionPaymentConfig(
  collectionId: string,
  config: CollectionPaymentConfig
) {
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgSetCollectionPaymentConfig",
    value: {
      collectionId,
      config
    }
  };
  
  return await Claims.broadcast(msg);
}

interface NetworkFeeParams {
  // Read-only network parameters set by governance
  readonly platformFee: string;     // Platform fee percentage
  readonly networkDaoFee: string;   // Network DAO fee percentage
  readonly evaluatorFee: string;    // Evaluator fee percentage
}

async function queryNetworkFeeParams(): Promise<NetworkFeeParams> {
  const query = `
    query NetworkParams {
      claims {
        params {
          platformFee
          networkDaoFee
          evaluatorFee
        }
      }
    }
  `;

  return await client.query({ query });
}

// Native blockchain tokens
const nativeTokens = {
  type: "native",
  denom: "uixo",     // IXO native token
  minAmount: "1000"  // 1000 uixo (1 IXO)
};

// IBC tokens from other chains
const ibcTokens = {
  type: "ibc",
  denom: "ibc/HASH", // IBC token denomination
  minAmount: "1000000"
};

// CW20 tokens (CosmWasm tokens)
const cw20Tokens = {
  type: "cw20",
  denom: "contract_address", // CW20 contract address
  minAmount: "1000000"
};

interface PaymentProcessing {
  claimId: string;
  payment: {
    amount: string;
    denom: string;
  };
  payer: string;
}

async function processClaimPayment(
  params: PaymentProcessing
) {
  // Fee distribution is handled automatically based on
  // network governance parameters
  const msg = {
    typeUrl: "/ixo.claims.v1beta1.MsgProcessPayment",
    value: {
      ...params
    }
  };
  
  return await Claims.broadcast(msg);
}

Configure Collection Payments
- Enable/disable payments
- Set accepted tokens
- Define minimum amounts
- Set optional maximums
Network Fee Structure
- Query current fee parameters
- View governance-set rates
- Monitor fee updates
- Track distributions
Process Payments
- Validate payment amount
- Process token transfer
- Automatic fee splitting
- Record transactions

Supported Token Types

Native blockchain tokens (uixo)
IBC tokens (cross-chain)
CW20 tokens (CosmWasm)
Custom token standards

Network Parameters

Governance-set fees
Network-wide standards
Transparent rates
Automatic compliance

Distribution Rules

Governance controlled
Automatic splitting
Instant distribution
Transparent tracking

Payment Security

Payment validation
Transaction verification
Error handling
Refund processing

Implementation Examples

Best Practices

Data Integrity

Validate input data
Include cryptographic proofs
Maintain audit trails
Version control

Verification

Use multiple verifiers
Implement timeouts
Handle disputes
Record evidence

Privacy

Protect sensitive data
Control access
Encrypt when needed
Manage permissions

Integration

Handle errors gracefully
Implement retries
Monitor performance
Log activities

Developer Resources

API Reference

Claims module API documentation

SDK Guide

Client SDK implementation guide

Examples

Implementation examples

GitHub

Claims module source code

For technical support or questions about Claims Management, join our Developer Community or contact our Developer Relations Team.

Get Started

Guides

Platforms

Developers

Articles

Overview

Claim Structure

Claim Collections

Agent Authorization

Role Configuration

Credential Management

Access Control

Claim Evaluation & Disputes

Payment Automations

Supported Token Types

Network Parameters

Distribution Rules

Payment Security

Implementation Examples

Best Practices

Data Integrity

Verification

Privacy

Integration

Developer Resources

API Reference

SDK Guide

Examples

GitHub

Get Started

Guides

Platforms

Developers

Articles

​Overview

​Claim Structure

​Claim Collections

​Agent Authorization

Role Configuration

Credential Management

Access Control

​Claim Evaluation & Disputes

​Payment Automations

Supported Token Types

Network Parameters

Distribution Rules

Payment Security

​Implementation Examples

​Best Practices

Data Integrity

Verification

Privacy

Integration

​Developer Resources

API Reference

SDK Guide

Examples

GitHub

Overview

Claim Structure

Claim Collections

Agent Authorization

Claim Evaluation & Disputes

Payment Automations

Implementation Examples

Best Practices

Developer Resources