ProofRails SDK

Beginner friendly SDK for creating blockchain verifiable ISO 20022 payment receipts

Create compliant, auditable payment receipts with just a few lines of code. No blockchain expertise required.

Features

• Zero coding knowledge required, use simple templates
• ISO 20022 compliant, generates standard banking messages
• Blockchain verified, receipts anchored on Flare blockchain
• Tamper proof, cryptographic evidence bundles
• Real time updates, live receipt status via SSE
• Works everywhere, TypeScript, JavaScript, Node.js, browsers

🚀 Zero Configuration Required

The SDK automatically connects to our production middleware. No backend setup needed!

• ✅ Just install and use
• ✅ Automatic API endpoint configuration
• ✅ Built-in retry logic and error handling
• ✅ Production-ready out of the box

Installation

npm install @proofrails/sdk
# or
yarn add @proofrails/sdk
# or
pnpm add @proofrails/sdk

Getting Your API Key

Before using the SDK, you need an API key:

Option 1: Automatic (Recommended for Beginners)

import ProofRails from '@proofrails/sdk';

// Creates a new project and returns your API key
const { client, apiKey, projectId } = await ProofRails.createProject({
  label: 'My App'
});

console.log('Save this API key:', apiKey);
// Use the client that's already configured

Option 2: Manual

1. Visit https://www.flarestudio.xyz/sdk/proofrails-sdk/create-api-key
2. Create a new project
3. Copy your API key
4. Use it in your code (see below)

Quick Start

Option 1, Create New Project (Easiest)

import ProofRails from '@proofrails/sdk';

// Create a new project automatically
const { client, apiKey, projectId } = await ProofRails.createProject({
  label: 'My App'
});

console.log('Your API Key:', apiKey); // Save this
console.log('Your Project ID:', projectId);

Option 2, Use Existing API Key

import ProofRails from '@proofrails/sdk';

const proofrails = new ProofRails({
  apiKey: 'your-api-key-here'
});

Templates (Beginner Friendly)

Payment Receipt

const receipt = await proofrails.templates.payment({
  amount: 100,
  from: 'Alice',
  to: 'Bob',
  purpose: 'Freelance web development',
  transactionHash: '0x123...'
});

console.log('Receipt ID:', receipt.id);
console.log('Status:', receipt.status);

Donation Receipt

const receipt = await proofrails.templates.donation({
  amount: 50,
  donor: 'John Doe',
  organization: 'Red Cross',
  campaign: 'Disaster Relief 2024',
  transactionHash: '0x456...'
});

Escrow Release

const receipt = await proofrails.templates.escrow({
  amount: 1000,
  buyer: 'Alice',
  seller: 'Bob',
  escrowId: 'ESC-2024-001',
  releaseReason: 'Milestone 1 completed',
  transactionHash: '0x789...'
});

Grant Disbursement

const receipt = await proofrails.templates.grant({
  amount: 5000,
  grantee: 'Research Lab',
  grantor: 'Science Foundation',
  grantId: 'GR-2024-001',
  purpose: 'Climate change research',
  transactionHash: '0xabc...'
});

Refund

const receipt = await proofrails.templates.refund({
  amount: 25,
  originalPayment: 'receipt-id-123',
  reason: 'Product returned',
  customer: 'Jane Smith',
  transactionHash: '0xdef...'
});

Core Operations

Get Receipt

const receipt = await proofrails.receipts.get('receipt-id');

console.log(receipt.status);
console.log(receipt.amount);
console.log(receipt.anchorTx);

List Receipts

const { items, total } = await proofrails.receipts.list({
  limit: 10,
  status: 'anchored'
});

items.forEach(r => {
  console.log(r.id, r.amount);
});

Download Artifacts

const artifacts = await proofrails.receipts.getArtifacts('receipt-id');

console.log('ISO XML:', artifacts.pain001Url);
console.log('Bundle:', artifacts.bundleUrl);
console.log('Manifest:', artifacts.manifestUrl);

Verification

Verify Receipt

const verification = await proofrails.verify.byReceiptId('receipt-id');

if (verification.valid && verification.onChain) {
  console.log('Receipt is valid and on chain');
  console.log('Anchor TX:', verification.anchorTx);
}

Verify by Bundle Hash

const verification = await proofrails.verify.byHash('0x123...');

Get Verification Proof

const proof = await proofrails.verify.getProof('receipt-id');

console.log('Bundle Hash:', proof.bundleHash);
console.log('Block Number:', proof.blockNumber);
console.log('Timestamp:', proof.timestamp);

Live Updates

const listener = proofrails.events.listen('receipt-id', update => {
  console.log('Status:', update.status);

  if (update.status === 'anchored') {
    console.log('Receipt is now on chain');
    listener.stop();
  }
});

React Integration (Hooks)

The SDK includes built-in React hooks for easy integration:

1. Wrap your app with ProofRailsProvider

// app/providers.tsx
'use client';

import { ProofRailsProvider } from '@proofrails/sdk/react';

export function Providers({ children }) {
  // Option 1: Env var (recommended)
  // PROOFRAILS_API_KEY must be set in .env.local
  // NEXT_PUBLIC_PROOFRAILS_BASE_URL (optional)
  return (
    <ProofRailsProvider apiKey={process.env.NEXT_PUBLIC_PROOFRAILS_API_KEY}>
      {children}
    </ProofRailsProvider>
  );
}

2. Use Hooks in Components

// app/payment/page.tsx
'use client';

import { useProofRailsPayment } from '@proofrails/sdk/react';

export default function PaymentPage() {
  const { createPayment, isLoading, error, receipt } = useProofRailsPayment();

  const handlePay = async () => {
    try {
      await createPayment({
        amount: 100,
        from: '0x123...',
        to: '0x456...',
        purpose: 'Coffee',
        transactionHash: '0xabc...'
      });
      alert('Receipt Created!');
    } catch (err) {
      console.error(err);
    }
  };

  return (
    <button onClick={handlePay} disabled={isLoading}>
      {isLoading ? 'Processing...' : 'Create Receipt'}
    </button>
  );
}

Embeddable Widgets

Generate Widget

const widget = proofrails.embed.widget('receipt-id', {
  theme: 'light',
  width: '100%',
  height: '400px'
});

document.getElementById('receipt').innerHTML = widget.iframeHtml;

Full Page URL

const pageUrl = proofrails.embed.fullPage('receipt-id');

Networks

const proofrails = new ProofRails({
  apiKey: 'your-key',
  network: 'coston2'
});

const proofrails = new ProofRails({
  apiKey: 'your-key',
  network: 'flare'
});

License

MIT

Support

• Documentation, https://www.flarestudio.xyz/sdk/proofrails-sdk/overview
• Repository, https://github.com/Elite-tch/Proofrails-sdk.git
• Email, [email protected]

Made with ❤️ by ProofRails