Skip to content

PROGRAMS.md

Latest commit

 

History

History
72 lines (47 loc) · 4.09 KB

PROGRAMS.md

File metadata and controls

72 lines (47 loc) · 4.09 KB
Raw

PowerChain Programs

Solana controller

programs/powerchain-token is the Anchor controller for the canonical PWRC Token-2022 mint. Version 1.2.1 supports:

  • validation of the nine-decimal PWRC mint and required extensions;
  • one-time fixed-supply issuance and permanent mint-authority removal;
  • holder-authorized checked transfers and burns;
  • protocol pause and two-step authority transfer;
  • idempotent payment transfers backed by receipt PDAs;
  • base-unit arithmetic with checked u128 fee calculations;
  • structured events for transfers, payments, burns, issuance, and pause changes.

The canonical Token-2022 program is:

TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

A payment receipt is derived from:

["pwrc-payment", state PDA, 32-byte payment ID]

The payment ID must be generated by the payment service and persisted before submission. Reusing it causes the receipt account initialization to fail, preventing accidental duplicate execution through this instruction.

Pay, x402, and MPP boundary

The agent-facing Pay integration is documented in skills/pay/SKILL.md. It can discover paid API providers and complete user-approved HTTP 402 payments through a local Pay client. It is deliberately outside the Anchor and Move programs.

The on-chain programs do not trust an HTTP response, QR code, payment URL, provider callback, or agent tool result as proof of settlement. Application services must independently validate the final chain transaction, expected asset, recipient, amount, reference, finality, and replay status before updating an order. No scan, deep link, or 402 response may trigger an automatic transfer without explicit wallet or local-user authorization.

Token-2022 fee accounting

PWRC transfers use transfer_checked with nine decimals. The program records the fee implied by its configured basis points and maximum cap, while Token-2022 applies and withholds the actual transfer fee. Settlement systems must inspect the confirmed transaction and Token-2022 account state before marking a payment complete.

Sui package

The Move package in contract/ remains a wrapped-PWRC bridge scaffold with capability controls, pause state, replay protection, and supply accounting. It is not a production bridge without independent review and finalized custody rules.

Build and test

pnpm program:build
pnpm program:test
pnpm anchor:test
pnpm sui:test

Required local tools are Anchor CLI, Rust/Cargo, Solana CLI, and Sui CLI. Deployment keypairs must not be committed.

Release controls

  • Build and test on localnet and devnet before mainnet deployment.
  • Confirm deployed program IDs match Anchor.toml and checked-in configuration.
  • Confirm mint decimals, supply, extension authorities, and fee parameters on-chain.
  • Test duplicate payment IDs, insufficient funds, paused state, and maximum-fee boundaries.
  • Keep upgrade and fee authorities in hardware-backed or managed custody.
  • Obtain an independent security audit before production deployment.

TOML and release configuration

  • Root Cargo.toml centralizes exact Anchor and Token-2022 dependency versions.
  • The program crate inherits workspace version, edition, license, repository, homepage, and minimum Rust version.
  • Release builds enable overflow checks, fat LTO, one code-generation unit, symbol stripping, and abort-on-panic behavior.
  • Anchor.toml pins Anchor CLI 0.32.1 and uses pnpm for TypeScript integration tests.
  • contract/Move.toml remains separate because the Sui wrapper is an independent package and deployment domain.

Pay Kit implementation

The application now exposes a sample paid HTTP route through @solana/pay-kit at /api/v1/pay-kit/report. The gate supports the configured MPP/x402 protocol preference and stablecoin settlement assets. This integration remains off-chain application middleware: the Anchor program does not parse HTTP credentials, trust payment headers, or authorize PWRC delivery from a Pay Kit receipt alone. Any flow that converts a paid API action into an on-chain PWRC transfer must still submit and validate the corresponding program instruction and idempotent payment receipt PDA.