@algopayoracle/oracle-sdk 1.0.0

package/src/AlgoPayClient.js

@@ -0,0 +1,298 @@
+/**
+ * AlgoPay Oracle SDK — AlgoPayClient
+ *
+ * Main entry point. Wraps OracleSigner + Algorand submission + ProofVerifier.
+ *
+ * Design:
+ *   - Provider-agnostic at the credential layer: verifyAndCommit() accepts a
+ *     PaymentEvent from any adapter (Razorpay, Stripe, UPI, manual).
+ *   - The payment rail (how money moved) is the adapter's concern.
+ *   - The credential (proof of payment) is always APC-1.
+ *   - One canonical proof path — no legacy branches, no format drift.
+ *
+ * Quick start:
+ *   const client = new AlgoPayClient({
+ *     mnemonic: process.env.ORACLE_MNEMONIC,
+ *     network:  "testnet",
+ *     appId:    Number(process.env.ALGO_APP_ID),
+ *   });
+ *
+ *   const result = await client.verifyAndCommit({
+ *     payment_id: "pay_XXXXXXX",
+ *     amount:     100,
+ *     action:     "unlock",
+ *     provider:   "razorpay",   // optional — enables cross-provider replay protection
+ *   });
+ */
+
+const algosdk      = require("algosdk");
+const { OracleSigner }  = require("./OracleSigner");
+const { ProofVerifier } = require("./ProofVerifier");
+const { createClients } = require("./networks");
+const { toAPC1 }        = require("./apc1");
+const { ConfigError }   = require("./errors");
+
+class AlgoPayClient {
+  /**
+   * @param {object} opts
+   * @param {string}   opts.mnemonic          - 25-word oracle account mnemonic
+   * @param {"localnet"|"testnet"|"mainnet"} [opts.network]
+   * @param {number}   [opts.appId]           - deployed AlgoPayOracle App ID
+   * @param {algosdk.Algodv2}  [opts.algod]   - custom algod (overrides network)
+   * @param {algosdk.Indexer}  [opts.indexer] - custom indexer
+   * @param {string}   [opts.explorerBase]    - custom explorer URL
+   */
+  constructor({ mnemonic, network = "testnet", appId = null, algod, indexer, explorerBase } = {}) {
+    if (!mnemonic) throw new ConfigError("mnemonic is required");
+
+    this.network = network;
+    this.appId   = appId;
+    this.signer  = new OracleSigner(mnemonic);
+
+    if (algod && indexer) {
+      this.algod        = algod;
+      this.indexer      = indexer;
+      this.explorerBase = explorerBase || "";
+    } else {
+      const clients     = createClients(network);
+      this.algod        = clients.algod;
+      this.indexer      = clients.indexer;
+      this.explorerBase = explorerBase || clients.config.explorerBase;
+    }
+
+    this.verifier = new ProofVerifier({ indexer: this.indexer, network });
+  }
+
+  // ── Core API ──────────────────────────────────────────────────────────────
+
+  /**
+   * Sign a payment proof and commit it to Algorand.
+   * This is the only method most integrations need.
+   *
+   * @param {object} payment
+   * @param {string} payment.payment_id  - provider-issued payment reference
+   * @param {number} payment.amount      - integer fiat amount
+   * @param {string} [payment.action]    - "unlock" | "mint" | "vote" | any string
+   * @param {string} [payment.currency]  - ISO 4217 (default: "INR")
+   * @param {string} [payment.provider]  - payment rail label (enables namespaced replay protection)
+   *
+   * @returns {Promise<{
+   *   txId:         string,   — confirmed Algorand transaction ID
+   *   proof:        object,   — internal signed proof
+   *   apc1:         object,   — APC-1 standardized credential
+   *   explorerUrl:  string,
+   *   verifyUrl:    string,
+   *   access_seconds: number
+   * }>}
+   */
+  async verifyAndCommit({ payment_id, amount, action = "unlock", currency = "INR", provider = "unknown" }) {
+    const proof = this.signer.sign({ payment_id, amount, action, currency, provider }, this.appId);
+    const txId  = await this._submitProof(proof);
+
+    return {
+      txId,
+      proof,
+      apc1:           toAPC1(proof, { network: this.network, appId: this.appId, provider }),
+      explorerUrl:    `${this.explorerBase}/transaction/${txId}`,
+      verifyUrl:      `/verify-proof/${txId}`,
+      access_seconds: 300,
+    };
+  }
+
+  /**
+   * Verify a proof by txId (indexer lookup).
+   * @param {string} txId
+   * @param {object} [opts]
+   */
+  async verifyProof(txId, opts = {}) {
+    return this.verifier.verifyTxn(txId, opts);
+  }
+
+  /**
+   * Verify a proof object offline (no network).
+   * @param {object} proof
+   * @param {object} [opts]
+   */
+  verifyProofOffchain(proof, opts = {}) {
+    return this.verifier.verifyOffchain(proof, opts);
+  }
+
+  // ── Oracle rotation ───────────────────────────────────────────────────────
+
+  /**
+   * Register a new oracle in the contract. Creator-only.
+   * @param {string} addressOrBase64 - Algorand address or base64 pubkey
+   * @returns {Promise<string>} txId
+   */
+  async addOracle(addressOrBase64) {
+    if (!this.appId) throw new ConfigError("appId required for oracle management");
+    return this._oracleAdminCall("add_oracle", AlgoPayClient._toPubKeyBytes(addressOrBase64));
+  }
+
+  /**
+   * Deregister an oracle. Creator-only. Cannot remove the last oracle.
+   * @param {string} addressOrBase64
+   * @returns {Promise<string>} txId
+   */
+  async removeOracle(addressOrBase64) {
+    if (!this.appId) throw new ConfigError("appId required for oracle management");
+    return this._oracleAdminCall("remove_oracle", AlgoPayClient._toPubKeyBytes(addressOrBase64));
+  }
+
+  /**
+   * Check if an oracle pubkey is registered in the contract.
+   * @param {string} addressOrBase64
+   * @returns {Promise<boolean>}
+   */
+  async isOracleRegistered(addressOrBase64) {
+    if (!this.appId) throw new ConfigError("appId required");
+    const pubkey = AlgoPayClient._toPubKeyBytes(addressOrBase64);
+    const params = await this.algod.getTransactionParams().do();
+    const method = new algosdk.ABIMethod({
+      name: "is_oracle", args: [{ name: "pubkey", type: "byte[]" }], returns: { type: "bool" },
+    });
+    const signer = algosdk.makeBasicAccountTransactionSigner(this.signer.account);
+    const atc    = new algosdk.AtomicTransactionComposer();
+    atc.addMethodCall({
+      appID: this.appId, method,
+      methodArgs: [Buffer.from(pubkey)],
+      boxes:      [{ appIndex: 0, name: Buffer.from(pubkey) }],
+      sender:     this.signer.address, suggestedParams: params, signer,
+    });
+    const result = await atc.simulate(this.algod);
+    return result.methodResults[0].returnValue;
+  }
+
+  // ── Contract stats ────────────────────────────────────────────────────────
+
+  async getTotalVerified() {
+    if (!this.appId) throw new ConfigError("appId required");
+    const info  = await this.algod.getApplicationByID(this.appId).do();
+    const state = info.params["global-state"] || [];
+    const entry = state.find(s => Buffer.from(s.key, "base64").toString() === "total_verified");
+    return entry ? Number(entry.value.uint) : 0;
+  }
+
+  async getOracleCount() {
+    if (!this.appId) throw new ConfigError("appId required");
+    const info  = await this.algod.getApplicationByID(this.appId).do();
+    const state = info.params["global-state"] || [];
+    const entry = state.find(s => Buffer.from(s.key, "base64").toString() === "oracle_count");
+    return entry ? Number(entry.value.uint) : 0;
+  }
+
+  // ── Identity ──────────────────────────────────────────────────────────────
+
+  getAddress()         { return this.signer.address; }
+  getPublicKeyBase64() { return this.signer.getPublicKeyBase64(); }
+  getPublicKeyBytes()  { return this.signer.getPublicKeyBytes(); }
+  getExplorerUrl(txId) { return `${this.explorerBase}/transaction/${txId}`; }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  async _submitProof(proof) {
+    const params = await this.algod.getTransactionParams().do();
+    params.flatFee = true;
+    params.fee     = Math.max(Number(params.minFee ?? 1000), 1000) * 8;
+
+    // proof JSON in note = the anchor. Indexer picks this up for verifyProof().
+    const note = new TextEncoder().encode(JSON.stringify(proof));
+
+    if (this.appId) {
+      const oraclePubKeyBytes = this.signer.getPublicKeyBytes();
+
+      const verifyMethod = new algosdk.ABIMethod({
+        name: "verify_payment",
+        args: [
+          { name: "payment_id",    type: "string" },  
+          { name: "action",        type: "string" },
+          { name: "amount",        type: "uint64" },
+          { name: "currency",      type: "string" },
+          { name: "timestamp",     type: "uint64" },
+	  { name: "app_id",        type: "uint64" },
+          { name: "oracle_pubkey", type: "byte[]" },
+          { name: "signature",     type: "byte[]" },
+        ],
+        returns: { type: "bool" },
+      });
+
+      const nopMethod = new algosdk.ABIMethod({
+        name: "nop", args: [], returns: { type: "void" },
+      });
+
+      const signer = algosdk.makeBasicAccountTransactionSigner(this.signer.account);
+      const atc    = new algosdk.AtomicTransactionComposer();
+
+      for (let i = 1; i <= 3; i++) {
+        atc.addMethodCall({
+          appID: this.appId, method: nopMethod, methodArgs: [],
+          sender: this.signer.address, suggestedParams: params,
+          note: new TextEncoder().encode(`pad${i}`), signer,
+        });
+      }
+
+      atc.addMethodCall({
+        appID:      this.appId,
+        method:     verifyMethod,
+        methodArgs: [
+          proof.canonical_id,                              // namespaced box key
+          proof.action,
+          proof.amount,
+          proof.currency,
+          proof.timestamp,
+	  this.appId,
+          Buffer.from(oraclePubKeyBytes),
+          Buffer.from(proof.signature, "base64"),
+        ],
+        boxes: [
+          { appIndex: 0, name: Buffer.from(oraclePubKeyBytes) },             // oracle registry
+          { appIndex: 0, name: new TextEncoder().encode(proof.canonical_id) }, // replay lock
+        ],
+        sender: this.signer.address, suggestedParams: params, note, signer,
+      });
+
+      const result = await atc.execute(this.algod, 6);
+      return result.txIDs[3];
+
+    } else {
+      // Anchor mode — 0-ALGO self-payment, proof JSON in note field
+      const txn = algosdk.makePaymentTxnWithSuggestedParamsFromObject({
+        sender: this.signer.address, receiver: this.signer.address, amount: 0,
+        note, suggestedParams: params,
+      });
+      const signed = txn.signTxn(this.signer.account.sk);
+      const { txid } = await this.algod.sendRawTransaction(signed).do();
+      await algosdk.waitForConfirmation(this.algod, txid, 6);
+      return txid;
+    }
+  }
+
+  async _oracleAdminCall(methodName, pubkeyBytes) {
+    const params = await this.algod.getTransactionParams().do();
+    params.flatFee = true;
+    params.fee     = Math.max(Number(params.minFee ?? 1000), 1000) * 2;
+
+    const method = new algosdk.ABIMethod({
+      name: methodName, args: [{ name: "pubkey", type: "byte[]" }], returns: { type: "void" },
+    });
+    const signer = algosdk.makeBasicAccountTransactionSigner(this.signer.account);
+    const atc    = new algosdk.AtomicTransactionComposer();
+    atc.addMethodCall({
+      appID: this.appId, method,
+      methodArgs: [Buffer.from(pubkeyBytes)],
+      boxes:      [{ appIndex: 0, name: Buffer.from(pubkeyBytes) }],
+      sender: this.signer.address, suggestedParams: params, signer,
+    });
+    const result = await atc.execute(this.algod, 4);
+    return result.txIDs[0];
+  }
+
+  static _toPubKeyBytes(addressOrBase64) {
+    if (typeof addressOrBase64 === "string" && addressOrBase64.length === 58) {
+      return algosdk.decodeAddress(addressOrBase64).publicKey;
+    }
+    return Buffer.from(addressOrBase64, "base64");
+  }
+}
+
+module.exports = { AlgoPayClient };

package/src/OracleSigner.js

@@ -0,0 +1,142 @@
+/**
+ * AlgoPay Oracle SDK — OracleSigner
+ *
+ * Pure Ed25519 signing — no network calls.
+ * The credential layer is provider-agnostic: sign() accepts a PaymentEvent
+ * from any adapter and produces an APC-1 compatible signed proof.
+ *
+ * Replay protection namespacing:
+ *   On-chain box keys use `provider:payment_id` (canonical_id), not raw payment_id.
+ *   This prevents cross-provider collisions where two providers issue the same ID.
+ *   The contract only sees canonical_id — it does not know or care about providers.
+ */
+
+const algosdk = require("algosdk");
+const { ConfigError, InsufficientAmountError } = require("./errors");
+const { validatePaymentEvent } = require("./validate");
+
+const PROOF_PREFIX = "AlgoPay:v1:";
+const MIN_AMOUNT   = 100;
+
+class OracleSigner {
+  /** @param {string} mnemonic - 25-word Algorand mnemonic */
+  constructor(mnemonic) {
+    if (!mnemonic) throw new ConfigError("mnemonic is required");
+    try {
+      this.account = algosdk.mnemonicToSecretKey(mnemonic);
+    } catch (e) {
+      throw new ConfigError(`Invalid mnemonic: ${e.message}`);
+    }
+    this.address = this.account.addr.toString();
+  }
+
+  /**
+   * Sign a payment proof.
+   *
+   * @param {object} payload
+   * @param {string} payload.payment_id  - provider-issued payment reference
+   * @param {number} payload.amount      - integer fiat amount (e.g. 100 for ₹100)
+   * @param {string} [payload.action]    - intended Web3 action (default: "unlock")
+   * @param {string} [payload.currency]  - ISO 4217 (default: "INR")
+   * @param {string} [payload.provider]  - payment provider label (default: "unknown")
+   * @returns {object} signed proof — pass directly to AlgoPayClient._submitProof()
+   */
+  sign({ payment_id, amount, action = "unlock", currency = "INR", provider = "unknown"}, appId = 0) {
+    // Delegate validation to validatePaymentEvent — consistent typed errors
+    validatePaymentEvent({ payment_id, amount, action, currency, provider });
+
+    // canonical_id = namespaced box key used on-chain for replay protection.
+    // Prevents cross-provider replay: razorpay:pay_ABC != stripe:pay_ABC.
+    // "unknown" provider falls back to raw payment_id (demo/manual mode).
+    const canonical_id = provider !== "unknown"
+      ? `${provider}:${payment_id}`
+      : payment_id;
+
+    const timestamp = Math.floor(Date.now() / 1000) - 30;  // backdate 30s — absorbs signing + tx propagation latency
+    const message   = OracleSigner.buildMessage(canonical_id, action, currency, amount, timestamp, appId);
+    const sigBytes  = algosdk.signBytes(message, this.account.sk);
+
+    return {
+      payment_id,      // original provider ID — for display and logging
+      canonical_id,    // namespaced — used in signing and as on-chain box key
+      provider,
+      amount,
+      action,
+      currency:       currency.toUpperCase(),
+      timestamp,
+      app_id:         appId,
+      oracle_address: this.address,
+      signature:      Buffer.from(sigBytes).toString("base64"),
+    };
+  }
+
+  /**
+   * Build the raw message bytes for signing.
+   *
+   * Byte order (must match AlgoPayOracle.py verify_payment exactly):
+   *   AlgoPay:v1: + canonical_id + action + currency + amount(8B BE) + timestamp(8B BE)
+   *
+   * algosdk.signBytes prepends "MX" before the Ed25519 operation.
+   * The contract prepends "MX" manually before ed25519verify_bare.
+   * So the effective signed bytes are: MX + the message below.
+   *
+   * @param {string} canonical_id - namespaced payment ID (provider:payment_id)
+   * @param {string} action
+   * @param {string} currency
+   * @param {number} amount
+   * @param {number} timestamp - unix seconds
+   * @returns {Uint8Array}
+   */
+  static buildMessage(canonical_id, action, currency, amount, timestamp, appId = 0) {
+    const enc   = new TextEncoder();
+    const parts = [
+      enc.encode(PROOF_PREFIX),
+      enc.encode(canonical_id),
+      enc.encode(action),
+      enc.encode(currency.toUpperCase()),
+      algosdk.encodeUint64(amount),
+      algosdk.encodeUint64(timestamp),
+      algosdk.encodeUint64(appId),
+    ];
+    const total = parts.reduce((s, p) => s + p.length, 0);
+    const msg   = new Uint8Array(total);
+    let off = 0;
+    for (const p of parts) { msg.set(p, off); off += p.length; }
+    return msg;
+  }
+
+  /**
+   * Verify a proof's signature offline — no network, no indexer.
+   * Uses canonical_id if present, falls back to payment_id for backward compat.
+   *
+   * @param {object} proof
+   * @returns {boolean}
+   */
+  static verifyOffchain(proof) {
+    try {
+      const id      = proof.canonical_id || proof.payment_id;
+      const message = OracleSigner.buildMessage(
+        id, proof.action, proof.currency || "INR", proof.amount, proof.timestamp, proof.app_id || 0
+      );
+      const sigBytes = Buffer.from(proof.signature, "base64");
+      return algosdk.verifyBytes(message, sigBytes, proof.oracle_address);
+    } catch {
+      return false;
+    }
+  }
+
+  /** @returns {string} Base64 pubkey — paste into create() call at contract deploy */
+  getPublicKeyBase64() {
+    return Buffer.from(algosdk.decodeAddress(this.address).publicKey).toString("base64");
+  }
+
+  /** @returns {Uint8Array} Raw 32-byte Ed25519 public key */
+  getPublicKeyBytes() {
+    return algosdk.decodeAddress(this.address).publicKey;
+  }
+
+  /** @returns {string} Algorand address of this oracle */
+  getAddress() { return this.address; }
+}
+
+module.exports = { OracleSigner };

package/src/ProofVerifier.js

@@ -0,0 +1,132 @@
+/**
+ * AlgoPay Oracle SDK — ProofVerifier
+ *
+ * Verifies APC-1 proofs both off-chain (Ed25519 sig check) and
+ * on-chain (Algorand indexer transaction lookup).
+ *
+ * Verification chain:
+ *   1. APC-1 version supported
+ *   2. Required fields present and typed correctly
+ *   3. canonical_id format sane (provider:payment_id or raw id)
+ *   4. Proof not expired
+ *   5. Oracle address filter (optional)
+ *   6. Action filter (optional)
+ *   7. Ed25519 signature verified using canonical_id (not payment_id)
+ */
+
+"use strict";
+
+const { OracleSigner }    = require("./OracleSigner");
+const { validateAPC1Structure, isSupportedVersion, isExpired } = require("./apc1");
+const { InvalidSignatureError, ProofExpiredError } = require("./errors");
+
+class ProofVerifier {
+  /**
+   * @param {object} opts
+   * @param {object}  opts.indexer  - algosdk.Indexer instance
+   * @param {string}  [opts.network]
+   */
+  constructor({ indexer, network = "testnet" } = {}) {
+    this.indexer = indexer;
+    this.network = network;
+  }
+
+  /**
+   * Verify an APC-1 proof object offline — no network calls.
+   *
+   * @param {object} proof
+   * @param {object} [opts]
+   * @param {string} [opts.expectedOracleAddress]
+   * @param {string} [opts.expectedAction]
+   * @param {number} [opts.maxAgeSecs]         - default 300
+   * @returns {{ valid: boolean, reason?: string, proof?: object }}
+   */
+  verifyOffchain(proof, opts = {}) {
+    // 1. APC-1 version check — fail early on unknown versions
+    if (proof.apc && !isSupportedVersion(proof)) {
+      return { valid: false, reason: `unsupported APC version: "${proof.apc}"` };
+    }
+
+    // 2. Required fields (works for both full APC-1 and internal proof objects)
+    const required = ["payment_id", "canonical_id", "amount", "currency", "action", "timestamp", "oracle_address", "signature"];
+    for (const f of required) {
+      if (proof[f] == null) return { valid: false, reason: `missing required field: ${f}` };
+    }
+
+    // 3. canonical_id consistency check
+    //    If provider is set and not "unknown", canonical_id should start with "provider:"
+    if (proof.provider && proof.provider !== "unknown") {
+      const expected_prefix = `${proof.provider}:`;
+      if (!proof.canonical_id.startsWith(expected_prefix) && proof.canonical_id !== proof.payment_id) {
+        return { valid: false, reason: `canonical_id "${proof.canonical_id}" does not match provider "${proof.provider}"` };
+      }
+    }
+
+    // 4. Expiry
+    const maxAge = opts.maxAgeSecs ?? 300;
+    if (isExpired(proof, maxAge)) {
+      const age = Math.floor(Date.now() / 1000) - proof.timestamp;
+      return { valid: false, reason: `proof expired — age ${age}s exceeds maximum ${maxAge}s` };
+    }
+
+    // 5. Oracle address filter
+    if (opts.expectedOracleAddress && proof.oracle_address !== opts.expectedOracleAddress) {
+      return { valid: false, reason: `oracle address mismatch: expected ${opts.expectedOracleAddress}` };
+    }
+
+    // 6. Action filter
+    if (opts.expectedAction && proof.action !== opts.expectedAction) {
+      return { valid: false, reason: `action mismatch: expected "${opts.expectedAction}", got "${proof.action}"` };
+    }
+
+    // 7. Ed25519 signature — uses canonical_id (the on-chain replay key)
+    const sigValid = OracleSigner.verifyOffchain(proof);
+    if (!sigValid) return { valid: false, reason: "Ed25519 signature verification failed" };
+
+    return { valid: true, proof };
+  }
+
+  /**
+   * Verify a proof by fetching its anchor transaction from the Algorand indexer.
+   * The proof JSON is stored in the transaction's note field.
+   *
+   * @param {string} txId
+   * @param {object} [opts] - same as verifyOffchain opts
+   * @returns {Promise<{ valid: boolean, reason?: string, proof?: object, txId: string }>}
+   */
+  async verifyTxn(txId, opts = {}) {
+    if (!this.indexer) return { valid: false, reason: "indexer not configured", txId };
+
+    let info;
+    try {
+      info = await this.indexer.lookupTransactionByID(txId).do();
+    } catch (e) {
+      return { valid: false, reason: `indexer lookup failed: ${e.message}`, txId };
+    }
+
+    const txn = info.transaction;
+    if (!txn?.note) return { valid: false, reason: "transaction not found or has no note field", txId };
+
+    let proof;
+    try {
+      proof = JSON.parse(Buffer.from(txn.note, "base64").toString("utf8"));
+    } catch {
+      return { valid: false, reason: "note field is not valid JSON", txId };
+    }
+
+    const result = this.verifyOffchain(proof, opts);
+    return { ...result, txId };
+  }
+
+  /**
+   * Batch verify multiple txIds.
+   * @param {string[]} txIds
+   * @param {object}   [opts]
+   * @returns {Promise<Array>}
+   */
+  async verifyBatch(txIds, opts = {}) {
+    return Promise.all(txIds.map(id => this.verifyTxn(id, opts)));
+  }
+}
+
+module.exports = { ProofVerifier };

package/src/adapters/index.js

@@ -0,0 +1,4 @@
+const { RazorpayAdapter } = require("./razorpay");
+const { StripeAdapter }   = require("./stripe");
+ 
+module.exports = { RazorpayAdapter, StripeAdapter };