Polymer Web3.js Plugin

A plugin for Web3.js v4 that adds Polymer proof capabilities, allowing you to generate and verify cross-chain transaction proofs.

Installation

npm install polymer-web3js

Usage

// Import the plugin and Web3.js
const { Web3 } = require("web3");
const { addPolymerToWeb3 } = require("polymer-web3js");

// Create a Web3 instance
const web3 = new Web3("https://sepolia.optimism.io");

// Initialize the plugin with your Polymer API key
addPolymerToWeb3(web3, {
  apiKey: "YOUR_POLYMER_API_KEY",
  apiUrl: "https://proof.testnet.polymer.zone", // Optional: default testnet URL
});

// Now all transaction receipt objects will have Polymer methods
const receipt = await web3.eth.getTransactionReceipt("0x123...");

// Get Polymer proof (returns the raw proof)
const proof = await receipt.polymerProof({
  eventSignature: "Transfer(address,address,uint256)", // Use either eventSignature or logIndex
  // logIndex: 0, // Alternative to eventSignature
});

// Advanced usage with maxAttempts and interval
const proof = await receipt.polymerProof({
  logIndex: 0,
  maxAttempts: 20, // Maximum polling attempts
  interval: 3000, // Polling interval in ms
});

// Get proof job ID without waiting for completion
const { jobId, receipt: txReceipt } = await receipt.polymerProof({
  logIndex: 0,
  returnJob: true,
});

// Check status of a proof job
const status = await receipt.polymerProofStatus(jobId);

Configuration Options

When initializing the plugin with addPolymerToWeb3, you can provide these configuration options:

| Option | Description | Default | | ------------- | ------------------------------- | ------------------------------------ | | apiKey | Your Polymer API key (required) | - | | apiUrl | Polymer API URL | https://proof.testnet.polymer.zone | | maxAttempts | Maximum polling attempts | 20 | | interval | Polling interval in ms | 3000 | | timeout | Request timeout in ms | 60000 | | debug | Enable debug logging | false |

Receipt Methods

The plugin adds the following methods to transaction receipt objects:

receipt.polymerProof(options)

Request and retrieve a Polymer proof for this transaction receipt.

Options:

• eventSignature - The event signature to generate a proof for (e.g., "Transfer(address,address,uint256)")
• logIndex - The log index of the event to generate a proof for (alternative to eventSignature)
• maxAttempts - Maximum polling attempts (default: value from config)
• interval - Polling interval in ms (default: value from config)
• returnJob - If true, returns the job object instead of the proof

You must provide either eventSignature or logIndex.

Returns: Promise that resolves to the proof object, or if returnJob is true, an object with { jobId, receipt }.

receipt.polymerProofStatus(jobId)

Get the status of a Polymer proof job.

Parameters:

• jobId - The Polymer proof job ID

Returns: Promise that resolves to the job status object.

Examples

See the examples directory for complete examples:

• receipt.js - Shows how to work with transaction receipts and generate proofs from logs

To run the examples:

# First, create a .env file with your Polymer API key
echo "POLYMER_API_KEY=your_api_key_here" > .env

# Run the example
npm run receipt

License

MIT