Advanced Configuration of the Reclaim Protocol SDK

This guide provides detailed information on advanced configuration options for the Reclaim Protocol SDK across multiple platforms. These options allow you to customize and enhance your integration for specific use cases.

Advanced Options

Adding Context

The addContext method allows you to add additional information to your proof request. This context is reflected in the proof object, helping to identify and distinguish between different proof requests.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
reclaimProofRequest.addContext('0x1234567890abcdef', 'User registration proof')
 
const requestUrl = await reclaimProofRequest.getRequestUrl()

• contextId: A unique identifier for the context (hex address)
• Context message: Additional information about the proof request (string)

Setting Parameters

The setParams method allows you to set specific conditions that must be met for the proof to be generated. This is useful for selective triggering and manual verification flows.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
reclaimProofRequest.setParams({ // Params value must be a string
  minConnections: '500', 
  industry: 'Technology'
})
 
const requestUrl = await reclaimProofRequest.getRequestUrl()

Custom Redirect URL

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
reclaimProofRequest.setRedirectUrl('https://your-app.com/verification-complete')
 
const requestUrl = await reclaimProofRequest.getRequestUrl()

Custom Callback URL

The setAppCallbackUrl method allows you to specify a custom API endpoint where proofs will be sent upon successful generation.

const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
reclaimProofRequest.setAppCallbackUrl('https://your-api.com/receive-proofs')
 
const requestUrl = await reclaimProofRequest.getRequestUrl()

Exporting and Importing SDK Configuration

The SDK provides methods to export and import the entire configuration as a JSON string. This allows for flexible usage across different parts of your application.

// Export configuration
const reclaimProofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID'
)
 
const reclaimProofRequestConfig = reclaimProofRequest.toJsonString()
 
// On a different service or application import the configuration
const reclaimProofRequest = await ReclaimProofRequest.fromJsonString(reclaimProofRequestConfig)
const requestUrl = await reclaimProofRequest.getRequestUrl()

Verifying Proof Signatures

The SDK provides a method to verify the cryptographic signatures of proofs to ensure their authenticity. This is particularly useful when receiving proofs from users or application sources.

import { ReclaimProofRequest, verifyProof } from 'reclaim-sdk'
 
// make sure proofObject is of type Proof Object
const isValid = await verifyProof(proofObject)
if (isValid) {
  console.log('Proof is valid!')
} else {
  console.log('Invalid proof - signature verification failed')
}

Initialization Options

When initializing the SDK, you can pass additional options to customize its behavior:

const proofRequest = await ReclaimProofRequest.init(
  'YOUR_RECLAIM_APP_ID',
  'YOUR_RECLAIM_APP_SECRET',
  'YOUR_PROVIDER_ID',
  { log: true }
)

• log: When set to true, enables detailed logging for debugging purposes.

Understanding the Proof Structure

When using any Reclaim SDK (JavaScript, React Native, Flutter), a proof is generated and returned upon successful verification. This proof contains several key components that provide detailed information about the verification process. Below is a generic structure of a proof:

{
  "identifier": "unique_identifier_for_proof", // string
  "claimData": {
    "provider": "provider_type", // string
    "parameters": "verified_data_from_website", // stringified JSON object
    "owner": "owner_address", // string
    "timestampS": "timestamp_of_proof_generation", // int
    "context": "additional_context_information", // stringified JSON object
    "epoch": "epoch_number" // int
  },
  "signatures": [
    "signature_of_proof" // string
  ],
  "witnesses": [
    {
      "id": "witness_id", // string
      "url": "witness_url" // string
    }
  ],
  // publicData is optional and only available if provider supports it else it will be empty
  "publicData": {} // stringified JSON object
}

Key Components:

• identifier: A unique identifier for the proof.
• claimData: Contains detailed information about the claim, including:
  • provider: The type of provider used for verification.
  • parameters: The parameters used during the verification process.
  • owner: The address of the owner of the proof.
  • timestampS: The timestamp when the proof was generated.
  • context: Any additional context information related to the proof.
  • epoch: The epoch number indicating the version or state of the proof.
• signatures: A list of signatures that validate the proof.
• witnesses: Information about witnesses that observed the proof generation, including their ID and URL.
• publicData: Any public data associated with the proof.

This proof is typically received in the onSuccess callback of startVerificationSession method when using the default callbackUrl. However, if you have set a custom callbackUrl, you will receive this proof at your specified API endpoint.

Best Practices for Advanced Configuration

1. Security: Always prioritize security when configuring callbacks and parameters. Use HTTPS for all URLs and avoid passing sensitive data in parameters.

2. Error Handling: Implement robust error handling for all advanced configurations, especially when dealing with callbacks and redirects.

3. Testing: Thoroughly test your advanced configurations in a staging environment before deploying to production.

4. Documentation: Maintain clear documentation of your custom configurations, especially when using context or custom parameters.

By leveraging these advanced configuration options, you can create a more tailored and robust integration of the Reclaim Protocol into your application. If you have any questions about these advanced features, don't hesitate to reach out to our support team or community forums.

Happy coding with Reclaim Protocol!