PassNode Chain — On-Chain Settlement for PassNode

npm package: passnode-onchain

PassNode Chain keeps the familiar PassNode middleware experience while recording purchases and settlements on-chain. Use it when multiple partners need a verifiable ledger or when you want a protocol-supported revenue share.

• 🔗 Drop-in upgrade – reuse your passnode.rules.json and middleware wiring.
• 🧾 Immutable settlements – record credits, passes, and pay-per-use receipts on-chain.
• 💸 Protocol fee support – share a small percentage of every settlement with the PassNode ecosystem.
• 🛠 Hardhat project included – deploy the ledger contract with the scripts in this repo.

Prerequisites

• Node.js 18+
• Hardhat (bundled)
• RPC provider (Infura, Alchemy, etc.)
• Service signer key capable of posting transactions

Installation

npm install passnode passnode-onchain

You always install the base passnode package as well—the chain adapter augments it.

Deploy the Ledger Contract

1. Copy .env.example to .env in passnode-chain/ and fill in:

   • SEPOLIA_RPC_URL (or your preferred network)
   • PRIVATE_KEY (deployment signer)
   • PLATFORM_WALLET, PLATFORM_FEE_BPS, MIN_PLATFORM_FEE_WEI

2. Install dependencies and compile:

   npm install
   npx hardhat compile
   npm run build:abi

3. Deploy:

   npx hardhat run scripts/deploy.js --network sepolia

   The script prints the contract address—store it in your service config (e.g. .env).

4. Register plans via Hardhat console or a script:

   await ledger.registerUsagePlan(ethers.id('usage-basic'), ethers.parseEther('0.05'), 100);
   await ledger.registerPassPlan(ethers.id('weekly-pass'), ethers.parseEther('0.12'), 7);

Wire the Adapter into Your Service

const { createPassNode } = require('passnode');
const { createPassNodeChain } = require('passnode-onchain');

const chain = createPassNodeChain({
  rpcUrl: process.env.RPC_URL,
  signerKey: process.env.SERVICE_SIGNER_KEY,
  network: 'sepolia',
  contracts: {
    ledger: process.env.LEDGER_ADDRESS
  }
});

const gate = createPassNode({
  rulesPath: './passnode.rules.json',
  planType: 'usage',
  chain
});

The adapter exposes middleware parity—req.passnode is still populated with wallet, plan, and balance information. Behind the scenes, purchases are settled against your ledger contract.

Adapter Options

| Option | Required | Description | | --- | --- | --- | | rpcUrl | ✓ | HTTPS endpoint for the target network. | | signerKey | ✓ | Service key used to submit transactions. | | contracts.ledger | ✓ | Address of the deployed PassNodeLedger contract. | | network | ✕ | Named network (e.g. mainnet, sepolia) for presets. | | protocolFeeBps | ✕ | Override default fee in basis points (if negotiated). | | gasMultiplier | ✕ | Multiply estimated gas (default 1.2). | | onSettlement* hooks | ✕ | Handlers for monitoring success/error events. |

Platform Fees

Each settlement sends the greater of price * protocolFeeBps / 10_000 and minPlatformFeeWei to the platform wallet. Configure these constants in the contract during deployment or through owner transactions.

Events & Monitoring

The ledger contract emits events for every purchase and credit consumption. Subscribe via your indexer or use the adapter’s event emitters:

chain.on('settlement:success', (receipt) => {
  console.log('Settled usage on-chain', receipt.transactionHash);
});

chain.on('settlement:error', (error, context) => {
  console.error('Settlement failed', context.txHash, error);
});

Project Structure

passnode-chain/
├── contracts/
│   └── PassNodeLedger.sol
├── scripts/
│   ├── deploy.js
│   └── export-abi.js
├── src/
│   ├── index.js        # Adapter + helpers
│   └── index.d.ts
├── hardhat.config.js
└── README.md

Run npm run build:abi after compiling to copy the ABI into src/abi/ for the adapter.

Roadmap

• [ ] CLI for registering plans and inspecting balances
• [ ] ERC-20 currency support
• [ ] Batch settlement + retries
• [ ] Security audit and gas optimisations before production release

Further Reading

• PassNode Chain Docs
• PassNode Standard Docs
• Getting Started
• Frontend Donations

For questions or feedback, open an issue or reach out via the main PassNode repository. Donations collected through the /coffee page help us ship new features faster.