PowerChain | Payment Platform & Tokenomics

PowerChain Payment Platform is the public PWRC protocol application and development workspace. It combines a Next.js 16 interface, Solana Token-2022 tooling, wallet and purchase flows, Supabase persistence, an Anchor controller, and a Sui Move wrapper scaffold.

Illustrative documentation: The screenshots below are generated product mockups. They demonstrate intended application and payment flows, but they may not match the current production interface.

Application

Home	Dashboard	Wallet connection

Portfolio	Mobile	API documentation

The canonical application URL is configured with NEXT_PUBLIC_SITE_URL and defaults to https://powerchain.energy. The screenshot manifest is available from GET /api/v1/showcase; filter it with ?kind=application, payment, developer, or mobile. Client components can use useShowcase() or the application-wide useShowcaseContext() hook.

Payments

Purchase	Solana Pay	Pay Kit HTTP 402	Confirmation

Solana Pay flow

Parse request URL → create transfer → wallet approval → sign and broadcast
                  → find reference → validate transfer → deliver PWRC → invoice

@solana/pay handles payment URLs, QR transfer requests, transaction preparation, reference lookup, and merchant-side validation. Amount, mint, recipient, memo, references, confirmation status, and replay state must be independently verified before fulfillment.

Pay Kit flow

Request protected API → HTTP 402 challenge → local payment authorization
                      → settlement verification → protected response

@solana/pay-kit protects HTTP resources using x402 or MPP. The public configuration endpoint is GET /api/v1/pay-kit/status, while GET /api/v1/pay-kit/report demonstrates a paid route. Pay Kit receipts remain application-layer evidence and do not replace on-chain authorization rules.

Canonical PWRC profile

Property	Value
Name	PowerChain
Symbol	PWRC
Solana standard	Token-2022
Decimals	9
Maximum supply	18,440,000,000 PWRC
Inflation	None after fixed-supply finalization
Transfer fee	250 basis points (2.5%)
Default account state	Initialized
Metadata	Metadata Pointer + on-mint Token Metadata
Token-2022 program	TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

Token settings are centralized in config/token.json. Update that file first, then synchronize generated metadata rather than editing duplicated values manually.

Brand assets

The canonical token artwork is public/brand/coin.svg. The hero uses it through components/brand/coin.tsx, while components/pages/3d-hero-coin.tsx adds presentation-only depth and motion. Do not recreate or embed a separate hero token illustration.

Other brand assets:

public/
├── coin.svg
├── logo.png
├── logo.svg
├── pwrc.png
└── brand/
    ├── coin.svg
    ├── logo-dark.png
    ├── logo-light.png
    ├── logo.svg
    └── pwrc.png

Main capabilities

• Next.js 16 App Router with React 19 and TypeScript
• Responsive light and dark themes
• Real Solana wallet connection, balances, and transaction history
• Solana Pay QR checkout and merchant-side PWRC fulfillment
• Supabase SSR clients, migrations, uploads, and order persistence
• Solana devnet/mainnet cluster configuration
• Token-2022 mint creation with Metadata Pointer, Token Metadata, Transfer Fee, and Default Account State
• Anchor controller for fixed-supply issuance and authority finalization
• Sui Move wrapped-token and bridge scaffold
• Recharts tokenomics and deflationary visualizations
• Config-driven token metadata and generated keypair workflows

Requirements

• Node.js 22+
• pnpm 11.17.0 (pinned through packageManager)
• Solana CLI for deployment operations
• Anchor CLI and Rust/Cargo for program builds
• Sui CLI for Move builds and tests

Install and run

corepack enable
pnpm install --frozen-lockfile
pnpm dev

Open http://localhost:3000.

Production checks:

pnpm typecheck
pnpm build
pnpm metadata:validate

Deploy to Vercel

The repository includes vercel.json for a standard Next.js deployment. Vercel installs with the pinned pnpm version, runs pnpm build, and deploys Node.js functions in fra1 by default. Keep the function region close to the primary Supabase or Neon database region; change regions when your database is hosted elsewhere.

pnpm dlx vercel link
pnpm dlx vercel env pull .env.local
pnpm dlx vercel deploy

For a production deployment:

pnpm dlx vercel deploy --prod

Configure secrets in Vercel Project Settings rather than committing .env files. At minimum, review these groups before deployment:

• Site and network: NEXT_PUBLIC_SITE_URL, Solana RPC and cluster values.
• Database: DATABASE_PROVIDER, DATABASE_URL, DIRECT_URL, and Supabase credentials when enabled.
• Payments: merchant wallets, Pay Kit recipient/operator values, MPP secret, and payment callback secrets.
• Mail: MAIL_PROVIDER, sender details, provider API key, and MAIL_TEST_SECRET.
• WalletConnect: project ID and optional application metadata.

DATABASE_URL should use the provider's pooled/serverless endpoint for runtime traffic. DIRECT_URL should use a direct connection for Prisma migrations. Apply migrations from CI or an explicitly controlled release step before promoting the deployment:

pnpm db:generate
pnpm db:migrate:deploy

The Vercel configuration deliberately applies private, no-store to /api/v1/*. Purchase, wallet, invoice, upload, and payment endpoints can contain user-specific or settlement-sensitive data and must not be cached by a shared CDN. Public market or showcase responses should opt into caching inside their individual route handlers when appropriate.

Longer-running payment, invoice, token-send, and upload route handlers have explicit function-duration limits. server.ts remains available for self-hosted Node deployments, but Vercel uses App Router route handlers under app/api/ as functions. Preview deployments receive a Vercel-generated URL; keep NEXT_PUBLIC_SITE_URL set to the canonical production domain when generating payment links, callbacks, metadata, and email URLs.

Token configuration and metadata

Edit:

config/token.json

Then synchronize and validate:

npm run token:metadata:sync
npm run metadata:validate

Network mint addresses can be recorded with:

npm run token:mint:set -- devnet <MINT_ADDRESS>
npm run token:mint:set -- mainnetBeta <MINT_ADDRESS>

Local Solana keypairs

Generate named development keypairs from generate-keypairs.json:

npm run keypairs:generate
npm run keypairs:addresses

The generated keypairs.json is intentionally ignored by Git. Never commit private keys, merchant signing material, upgrade authorities, service-role keys, or private RPC credentials. For production, use hardware-backed or managed custody rather than repository files.

Create a devnet mint using the configured role names:

PWRC_KEYPAIRS_FILE=keypairs.json npm run token:create:devnet

Mainnet creation must use separately secured and funded keypairs:

PWRC_KEYPAIRS_FILE=/secure/path/keypairs.json npm run token:create:mainnet

Repository layout

app/                         Next.js routes and APIs
components/                  UI, wallet, payments, cluster, and brand components
config/token.json            Canonical token configuration
contract/                    Sui Move wrapper scaffold
data/tokenomics.ts           Canonical allocation and economic presentation data
lib/                         Solana, Supabase, security, transaction, and explorer helpers
migrations/                  Supabase SQL migrations and schemas
programs/powerchain-token/   Anchor Token-2022 controller
public/brand/                Canonical logo and token artwork
scripts/                     Keypair, metadata, mint, and validation utilities
token/pwrc/README.md         PWRC token documentation

Program workflows

npm run program:build
npm run program:test
npm run anchor:test
npm run sui:test

Read programs/powerchain-token/README.md and programs/powerchain-token/DEX_COMPATIBILITY.md before deployment or pool creation.

Security and deployment status

The included Anchor and Sui sources are implementation scaffolds and have not been independently audited. Do not deploy to mainnet until reviewers validate extension configuration, transfer-fee economics, mint finalization, treasury custody, merchant fulfillment, bridge attestations, replay protection, rate limits, upgrade authority, emergency procedures, and DEX compatibility.

A custom server.ts is included for deployments that require a Node server and health endpoint. Standard Next.js deployments may use next start without it. Request/session handling and security headers live in proxy.ts. The custom Node server is not used by the standard Vercel deployment.

Official properties

• Protocol website: https://powerchain.energy
• Tokenomics application: https://tokenomics.powerchain.app

License and disclaimer

See the repository license. PWRC documentation is technical information, not financial, legal, investment, or tax advice.

Hardened purchase checkout

The buy page offers fixed $10, $50, $100, and $250 checkout amounts. Receiving addresses are validated as canonical Solana public keys in both the browser and API. Zero-balance buyers, insufficient payment balances, unavailable market rates, and insufficient merchant inventory are rejected before a Solana Pay request is stored.

Payment fulfillment uses a unique reference per order, findReference, exact validateTransfer checks, an atomic fulfillment claim, Token-2022 merchant delivery, transaction-signature storage, and optional branded invoices. Configure market providers and invoice delivery in env/.env.example.

Database backends: Supabase or Prisma

The application can use the existing Supabase client repositories or an optional Prisma ORM repository layer against the same PostgreSQL database.

DATABASE_PROVIDER=supabase # or prisma
DATABASE_URL=postgresql://...
DIRECT_URL=postgresql://...

SUPABASE_URL=
SUPABASE_PUBLISHABLE_KEY=
SUPABASE_SECRET_KEY=
SUPABASE_JWKS_URL=
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=

Prisma is pinned to 6.19.0 because this project intentionally uses the requested prisma-client-js generator and keeps url and directUrl in schema.prisma. Prisma 7 moves connection URLs to prisma.config.ts and requires a different client setup.

npm install
npm run db:generate
npm run db:validate
npm run db:pull        # introspect an existing Supabase schema
npm run db:migrate     # development only
npm run db:migrate:deploy
npm run db:studio

Use DATABASE_URL for the application connection, normally a Supabase session pooler in hosted/serverless environments. Use DIRECT_URL for migrations and introspection. Supabase Auth, Storage, JWT, and row-level-security flows continue to use @supabase/ssr and @supabase/supabase-js; Prisma does not replace those services.

The shared repository entry point starts at lib/database/purchase-orders.ts. Browser hooks never import Prisma because Prisma is server-only.

Solana Pay wallet-provider flow

PowerChain supports both sides of a Solana Pay transfer request:

• createTransferRequest creates merchant payment URLs with a unique reference.
• prepareTransferRequest parses a solana: URL and constructs an unsigned native SOL or SPL-token transaction for the connected payer.
• useSolanaPayTransferRequest requires the user to review and explicitly approve the transaction before sending it.
• findAndValidateTransfer finds the reference and validates the exact recipient, amount, optional SPL mint, and reference before fulfillment.

The branded QR implementation is client-only and uses qr-code-styling with the canonical PWRC icon. A QR scan never signs or submits a transaction automatically.

All PWRC quantities are converted with decimal-string and bigint helpers. The application reads the mint's decimals from chain before merchant delivery and uses Token-2022 TransferChecked; it does not calculate base units with JavaScript floating-point arithmetic.

License

PowerChain Tokenomics is distributed under the MIT License. The package manifest declares "license": "MIT", and the full license terms are included in LICENSE.

pnpm and Prisma installation

This repository supports both npm and pnpm. The project pins pnpm through the packageManager field and keeps the Prisma CLI and generated client on the same version (6.19.0). Do not mix a Prisma 7 client with a Prisma 6 CLI.

Recommended pnpm setup

corepack enable pnpm
pnpm install
pnpm db:generate
pnpm db:validate
pnpm dev

pnpm 11 requires Node.js 22 or newer. pnpm-workspace.yaml explicitly allows the Prisma packages to run the installation scripts required to install engines and generate the client.

Repair a mismatched Prisma installation

An error path containing both @prisma+client@7.9.1 and prisma@6.19.0 means the existing pnpm virtual store or lockfile was produced from incompatible package versions. The manifest now forces both packages to 6.19.0.

From the repository root, run:

rm -rf node_modules .next pnpm-lock.yaml
corepack enable pnpm
pnpm install
pnpm exec prisma generate --schema=prisma/schema.prisma
pnpm exec prisma version

Or use the included repair command after pnpm is available:

pnpm prisma:repair

The output of pnpm exec prisma version should report prisma and @prisma/client as 6.19.0.

Do not keep both package-lock.json and pnpm-lock.yaml in active use. Pick one package manager per checkout and commit the corresponding lockfile.

Wallet context

The Solana adapter provider is wrapped by PowerChainWalletContextProvider. Application components should consume wallet state through:

import { usePowerChainWallet } from "@/hooks/use-powerchain-wallet";

const { address, connected, openWalletModal, disconnect } = usePowerChainWallet();

The context centralizes the wallet address, connection state, signing methods, disconnect action, and the PowerChain wallet-selection modal. It must remain inside the Solana WalletProvider, as configured in providers/app-providers.tsx.

pnpm native build scripts

pnpm 11 blocks dependency lifecycle scripts unless they are approved. The workspace allowlist includes Prisma engines, Next.js Sharp image processing, Solana and WalletConnect cryptographic dependencies, protobuf generation, and optional native WebSocket/USB helpers. Review this allowlist when dependencies change and remove packages that are no longer present in the lockfile.

To repair an installation after ERR_PNPM_IGNORED_BUILDS:

rm -rf node_modules .next
pnpm install
pnpm rebuild
pnpm exec prisma generate --schema=prisma/schema.prisma
pnpm lint
pnpm typecheck

Dependency installation troubleshooting

Use one package manager per checkout. This repository is pinned to pnpm 11.17.0 through the packageManager field.

rm -rf node_modules pnpm-lock.yaml package-lock.json .next
corepack enable
corepack prepare pnpm@11.17.0 --activate
pnpm install
pnpm deps:check

The Solana Pay dependency graph currently contains packages whose peer ranges require TypeScript 5.x. The repository therefore pins TypeScript to 5.9.3; do not run npm update to upgrade it independently to TypeScript 6.x.

pnpm 11 also fails installation when a dependency has an unreviewed lifecycle script. Approved packages are listed under allowBuilds in pnpm-workspace.yaml. Review and explicitly add any newly reported package instead of enabling all dependency scripts globally.

Solana Pay SDK errors and transaction requests

The Solana Pay integration normalizes the SDK's ParseURLError, CreateTransferError, FetchTransactionError, FindReferenceError, and ValidateTransferError into PowerChainSolanaPayError codes suitable for API responses and wallet UI messages. lib/solana-pay.ts supports transfer-request parsing and creation, transaction-request fetching, reference lookup, transfer validation, and official Solana Pay QR generation. Opening or scanning a payment URL never signs or submits a transaction automatically; the connected wallet must display the label, message, recipient, amount, token mint, and memo and require explicit approval.

Solana Pay SDK field compatibility

The Solana Pay layer now preserves the SDK request objects and exports compatible field types for wallet and merchant integrations:

• TransferRequestURLFields for encoded transfer links.
• TransferRequestURL for parsed transfer links.
• ValidateTransferFields for confirmed-transaction validation.
• References, which accepts either one PublicKey or an array of PublicKey values.

lib/solana-pay-fields.ts provides normalizeReferences, toValidateTransferFields, and createValidateTransferFields. Validation requires a positive BigNumber amount and can verify the recipient, optional SPL-token mint, reference keys, and memo. Display-only URL fields such as label and message are intentionally not part of on-chain transfer validation.

Pay Kit: paid HTTP endpoints with x402 and MPP

PowerChain includes a server-only integration with @solana/pay-kit for stablecoin-gated HTTP routes. Pay Kit uses the web-standard Request/Response interface, so the same dispatcher works inside Next.js route handlers. A request without valid payment proof receives 402 Payment Required; a compatible client signs and settles the stablecoin payment, retries the request with the payment credential, and receives the protected response only after settlement verification.

Implemented files:

lib/pay-kit/config.ts
lib/pay-kit/server.ts
types/pay-kit.ts
app/api/v1/pay-kit/status/route.ts
app/api/v1/pay-kit/report/route.ts

The public status endpoint reveals configuration readiness without exposing secrets:

curl http://localhost:3000/api/v1/pay-kit/status

The protected sample endpoint is:

curl -i http://localhost:3000/api/v1/pay-kit/report
# 402 Payment Required when Pay Kit is configured and no proof is supplied

pay curl -i http://localhost:3000/api/v1/pay-kit/report
# local user authorization, settlement, then 200 response

Enable it through the PAY_KIT_* values in env/.env.example. Deployed environments must provide a real recipient or operator signer. The application deliberately refuses to initialize a paid route with neither configured, preventing accidental use of Pay Kit's public demo signer. MPP also requires a stable challenge-binding secret. Use a persistent replay store before horizontal production scaling; the included setup is intended as a safe single-process integration baseline.

Pay Kit and the existing @solana/pay checkout serve different purposes:

• @solana/pay implements user-facing Solana Pay URLs, QR codes, transfer construction, reference lookup, and merchant validation.
• @solana/pay-kit gates HTTP resources using x402 or MPP and releases a response only after payment verification and settlement.

Neither an HTTP callback nor a 402 response is treated as PWRC program settlement proof. On-chain order fulfillment continues to validate the mint, recipient, amount, reference, confirmation state, and replay status independently.

pnpm installation and approved builds

The repository uses pnpm 11 workspace settings from pnpm-workspace.yaml. Dependency overrides are intentionally stored there because pnpm 11 no longer reads pnpm.overrides from package.json.

Install and approve required native/build dependencies with:

corepack enable
pnpm install
pnpm deps:approve-builds
pnpm deps:rebuild
pnpm deps:check

The approved build list includes Prisma engines, Next.js image tooling, Solana and WalletConnect native crypto dependencies, esbuild, and unrs-resolver. Keep strictDepBuilds: true; add a package to allowBuilds only after reviewing why it needs a lifecycle script.

bs58 and axios are not direct dependencies because the current codebase does not import them. Solana address and key encoding is handled by the installed Solana libraries, and HTTP requests use the platform fetch API. Add either package only when a direct import is introduced.

Development bundler

The default development and production scripts use Webpack for stability:

pnpm dev
pnpm build

Turbopack remains available as an opt-in path:

pnpm dev:turbo
pnpm build:turbo

If Turbopack reports an internal task-graph panic such as inner_of_uppers_lost_follower, clear its generated state before retrying:

pnpm next:cache:clean
pnpm dev:turbo

The Turbopack filesystem cache is disabled unless NEXT_TURBOPACK_FS_CACHE=true is set.

Database schemas and migrations

PowerChain ships two migration tracks over one PostgreSQL data model:

• Prisma / portable PostgreSQL: prisma/schema.prisma and prisma/migrations/ work with Neon, Supabase Postgres, and standard PostgreSQL.
• Supabase: supabase/migrations/ adds Supabase Auth foreign keys and Row Level Security policies.

For Neon or another serverless PostgreSQL host, configure a pooled DATABASE_URL for runtime queries and a direct DIRECT_URL for Prisma Migrate. For Supabase deployments that use Auth/RLS, apply the Supabase migration history with pnpm supabase:db:push. Do not apply both histories to the same new database.

Legal, cookies, PWA, and invoice mail

Legal documents are available at /legals, /legals/terms, /legals/privacy, and /legals/cookies. The application includes a consent banner that stores only necessary preferences until optional categories are accepted, plus a reusable RememberMeSelect for session or 30-day persistence.

Invoice delivery supports resend, postmark, and a development-only console provider through MAIL_PROVIDER. Test the selected provider with:

pnpm mail:test recipient@example.com

A guarded HTTP test is also available at POST /api/v1/mail/test; production requests require Authorization: Bearer $MAIL_TEST_SECRET.

Exit code 143 and dependency warnings

ELIFECYCLE exit code 143 means the process received SIGTERM; it is not a JavaScript exception by itself. The project runs Next.js through scripts/run-next.mjs, which removes inherited debugger flags from compiler workers and treats SIGINT/SIGTERM as a clean shutdown only for the development server. Production builds still fail on a termination signal so CI cannot hide a real timeout or memory limit.

Use the stable Webpack path after clearing generated state:

pnpm next:cache:clean
pnpm install
pnpm typecheck
pnpm build

Modern injected Solana wallets (Phantom, Solflare, Backpack, Coinbase Wallet, and compatible wallets) are discovered through Wallet Standard. The broad @solana/wallet-adapter-wallets aggregator was removed because it installed many unused legacy adapters and deprecated transitive packages. WalletConnect remains optional and is enabled only when NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID is configured.

A pnpm “deprecated subdependencies” line is informational and does not cause exit code 143. Inspect the remaining dependency owners with:

pnpm deps:deprecated

Do not add direct overrides for nested uuid, glob, Stellar, Torus, or WalletConnect packages unless their owning library officially supports the replacement version; forcing incompatible transitive versions can break signing or wallet sessions.

WalletConnect logging dependency

WalletConnect currently pulls in Pino through @walletconnect/logger. The project includes pino-pretty as a development dependency so Next.js can resolve Pino's optional development transport during compilation. Production logging remains structured unless an application logger explicitly enables the pretty transport.

After pulling this change, refresh the installation and Next.js cache:

pnpm install
pnpm next:cache:clean
pnpm dev

The browser message Lit is in dev mode is emitted by an upstream web-component dependency in development and is not an application failure. It should not appear in a production build.

Resilient purchase flow

The checkout now debounces fee quotes, prevents duplicate submissions in the browser, and sends a unique Idempotency-Key with every purchase creation request. The database stores this key under a unique partial index, so retries return the original order instead of creating a second payment request.

Payment status verification uses bounded exponential-backoff retries and request timeouts. The UI exposes explicit progress states for validation, inventory checks, request creation, payment confirmation, Token-2022 delivery, and completion. Merchant PWRC inventory is checked both before signing and immediately before fulfillment.

The fee card separates:

• PowerChain service fee;
• estimated Solana network fee;
• Token-2022 transfer fee and configured cap;
• gross and estimated net PWRC delivery.

Apply the matching Prisma or Supabase migration before deploying this flow:

pnpm db:migrate:deploy
# or
pnpm supabase:db:push

Configurable checkout and receipts

The checkout now uses a live, debounced quote endpoint and checks the connected wallet balance before creating a payment request. SOL is the default settlement method. Payment method metadata is centralized in constants/payment-methods.ts; Solana USDC can be exposed with NEXT_PUBLIC_ENABLE_USDC_PAYMENTS=true after the USDC settlement route is enabled.

GET /api/v1/payments/quote?amount=50&method=SOL

The quote includes the SOL/USD and PWRC/USD snapshots, payment amount, gross and net PWRC, service fee, Solana network reserve, and Token-2022 transfer fee. Completed purchases display a transaction receipt with payment and delivery explorer links and are stored locally in storage/invoices.ts for convenient access on the same browser.

Receipt behavior is configurable:

NEXT_PUBLIC_RECEIPT_CLOSE_MODE=manual     # manual | automatic
NEXT_PUBLIC_RECEIPT_AUTO_CLOSE_MS=9000
NEXT_PUBLIC_QUOTE_DEBOUNCE_MS=400
NEXT_PUBLIC_CONFIRMATION_POLL_MS=1800
NEXT_PUBLIC_CONFIRMATION_ATTEMPTS=6

Database migration 20260729000400_payment_methods_receipts adds payment-method, rate-snapshot, payment-amount, and confirmation timestamp fields to purchase orders. Apply either the Prisma or Supabase migration track, not both, for the same database.

Phase 1 architecture

The application now has stable top-level boundaries for API routes, server actions, service components, typed configuration, and shared constants.

app/actions/             Server-action entry points
app/api/v1/              Versioned route handlers
components/services/     Client service composition boundary
components/charts/       Chart component exports
components/tokenomics/   Tokenomics component exports
config/                  Typed runtime configuration
constants/               Stable route, wallet, cluster, explorer, and token constants
lib/api/                  Shared API client, errors, responses, pagination, and validation

New health endpoint:

GET /api/v1/health

Configuration is split by concern (app, api, prices, security, solana, storage, tokenomics, and wallet) so future provider and deployment upgrades do not require editing UI components. The original modules remain available for backward compatibility while features migrate incrementally to the new boundaries.

Runtime validation and utility dependencies

PowerChain uses zod for typed runtime validation, uuid for application-owned identifiers, and lodash for selected utility functions. Import lodash functions by module path, such as lodash/debounce, to avoid unnecessarily broad client bundles.

Server environment validation is available through getServerEnv() in lib/validation/env.ts. It validates URLs, numeric limits, provider choices, and core runtime settings before they are consumed.

import { getServerEnv } from "@/lib/validation/env";

const env = getServerEnv();
console.log(env.API_REQUEST_TIMEOUT_MS);

The deprecation notices emitted for WalletConnect clients, glob@10, lodash.isequal, and uuid@8 are transitive. They must be resolved by the packages that own those nested dependencies; direct application dependencies should not be used as unsafe package-manager overrides.

See CHANGELOG.md for release history.