How JomPaySol works, from wallet approval to vault settlement.

JomPaySol is a Solana payment vault app for coordinating shared token payments. Instead of tracking everything manually in chats or spreadsheets, a creator sets up a vault, assigns exact amounts to people, and shares links for each person to pay or claim.

The MVP supports two flows: GroupPay for collecting money from a group, and ClaimPay for distributing a funded pool to recipients.

It makes multi-person token payments easier to coordinate. Each participant gets a clear page showing the amount, deadline, assigned wallet, vault status, and the action they need to take.

The app also reads on-chain state so the vault page can show whether funds were deposited, claimed, released, refunded, or returned.

No. JomPaySol does not hold private keys and does not custody funds in a normal web account. Funds are held by Solana program-controlled vault accounts. Users still approve transactions from their own wallet extension.

For this MVP, the web app helps build the right Solana transaction and stores friendly metadata so the interface can show labels, descriptions, and invite links.

No. Never paste a private key into this app. You only connect a wallet, such as Phantom, and the wallet asks you to approve transactions.

The app can ask your wallet to sign a transaction, but the private key stays inside the wallet.

Use GroupPay when multiple people need to pay into one shared target. Examples include a trip split, group purchase, event deposit, team collection, DAO contribution, custodial operating wallet top-up, or vendor payment.

The vault only releases to the fixed destination wallet when the required amount is fully collected. That destination can be a vendor wallet, DAO treasury, custodial wallet, or any approved Solana wallet chosen at vault creation.

Once funded, any connected wallet can trigger the release. If the vault expires before it is fully funded, contributors can refund their own paid shares.

Use ClaimPay when one creator, company, team, or DAO wants to fund a payout pool first, then let approved recipients claim their assigned amounts. Examples include hackathon winnings, reimbursements, grants, rewards, bounties, payroll-like allowances, or community contributor payouts.

The creator deposits the full token amount into the vault during creation. Recipient wallets and payout amounts are fixed at vault creation, so the vault behaves like a controlled distribution pool rather than an open claim form.

Each recipient gets a personal claim link tied to their wallet. The connected wallet must match the assigned recipient wallet, recipients cannot claim more than their assigned amount, and each recipient can only claim once.

After the deadline, any connected wallet can trigger return of unclaimed funds back to the creator wallet. Claimed payouts stay with recipients; only unclaimed funds are returned.

The MVP uses exact allocations. For GroupPay, contributor shares must add up to the target before the vault is activated. For ClaimPay, recipient payouts must add up to the funded total.

This keeps the flow predictable: every token in the vault has an assigned purpose.

No. Each participant link is tied to one wallet address. If the connected wallet does not match the assigned wallet, the action is blocked.

This prevents someone from accidentally paying or claiming against another person's allocation.

No. The on-chain recipient account records whether the payout has already been claimed. If it is already claimed, the app disables the action and shows that no more action is needed.

The app supports approved SPL tokens from configuration. In the current setup, USDC and USDT-style devnet mints can be configured for testing.

Devnet USDC uses Circle's public test mint and can be funded from Circle's faucet. USDT is shown as a supported feature path, but its devnet mint must be configured by the project because there is no single reliable official public USDT devnet mint to hardcode.

The app shows a user-friendly currency selector. New vault creation is also checked against the program's on-chain token allowlist.

Use Solana's devnet faucet for test SOL. SOL is needed for transaction fees and account creation even when the vault token is USDC.

Use Circle's faucet for devnet USDC. For USDT, configure a known project test mint first; until then, treat USDT as a UI-supported feature rather than a faucet-backed public token.

Yes. Vendor, contributor, and recipient fields can accept a Solana wallet address or a registered .sol name from sns.id.

Before creating the vault, the app resolves every .sol name through Solana Name Service on mainnet and sends the resolved public key into the on-chain instructions and metadata store.

.sol names are human-friendly identity labels, but the final payment target is still a Solana public key. The app shows both when possible so users can verify the exact wallet.

Participant labels remain editable nicknames for the vault. The .sol name is displayed as secondary identity metadata when the wallet has a primary SNS domain.

SOL pays Solana transaction fees and account rent. Even if the payment token is USDC, the wallet still needs a small amount of SOL on the same network.

For claim links, a recipient may also need a token account created for the selected SPL token. That also requires a small amount of SOL.

Devnet is Solana's public testing network. It behaves like Solana, but the SOL and tokens are for testing and have no real market value.

This MVP is intended for devnet or localnet testing before any real-money launch.

Localnet is a Solana validator running on your own machine. It is useful for fast development because you can deploy and test the program locally without using public devnet.

Localnet state is separate from devnet. A vault created on localnet will not exist on devnet, and the reverse is also true.

It means the app, wallet, or program accounts are not pointing to the same Solana cluster. For example, your metadata may show a vault, but the configured RPC may not find the vault account on-chain.

If that happens, check the RPC URL, wallet network, program ID, and token mint configuration.

JomPaySol needs small-value payments, many participant-specific actions, public verification, and predictable settlement rules. Solana is a strong fit because transaction fees are low enough for contributors and recipients to interact directly without fees dominating the payment amount.

The user experience also benefits from fast confirmation. GroupPay and ClaimPay are coordination products: people need to see quickly that a share was paid, a payout was claimed, or a vault was released. A slow chain would make the product feel like manual back-office reconciliation.

Solana also has mature wallet and SPL token standards. Wallet Adapter gives the app a familiar wallet approval flow, SPL tokens provide stablecoin-style payments, and associated token accounts give a standard destination for each wallet-token pair.

The vault program uses Program Derived Addresses, or PDAs, for vault, contributor, and recipient accounts. PDAs let the program derive deterministic accounts from seeds such as creator wallet, vault ID, participant wallet, and program ID. That makes account lookup predictable and prevents the web app from inventing arbitrary state locations.

SPL token transfers are constrained by the program. The program checks the selected mint, expected vault token account, signer, participant record, deadline, and current vault status before moving funds. The frontend can prepare the transaction, but it cannot bypass those on-chain checks.

Solana's account model is useful here because the vault state is explicit. The app can read vault, contributor, and recipient accounts from RPC and compare that chain state against friendly metadata such as titles, labels, and invite links.

A normal database is useful for labels, descriptions, and links, but it should not be the source of truth for money movement. If payment state lived only in a backend database, users would need to trust the server operator not to rewrite balances or claim status.

With Solana, the critical rules run in the program: exact allocation, assigned wallet checks, one-time claim, release eligibility, refund eligibility, and token mint constraints. The database can go down or become stale, but the payment rules remain anchored to chain state.

This split is intentional: metadata is off-chain for usability, while settlement state is on-chain for verifiability.

Users still need SOL for transaction fees and token account creation, even when the vault uses USDC or USDT. That is why the Help page links to devnet faucets for testing.

The app also depends on RPC quality. If the configured RPC is slow or points to the wrong cluster, the UI may fail to read vault accounts even when metadata exists.

For production, Solana does not remove the need for security review, indexing, rate limiting, operational monitoring, authority management, and legal review. It gives the product a strong payment rail, but the surrounding product still needs production-grade controls.

Anchor is a Solana development framework. It helps define the on-chain program instructions, accounts, constraints, and generated IDL used by clients.

In this app, the Anchor program owns the vault logic: create vaults, add participants, deposit, claim, release, refund, return unclaimed funds, and sweep unaccounted excess tokens from terminal vaults.

A Solana program is on-chain code. It is similar to a smart contract. JomPaySol's program decides which accounts must sign, which token accounts are valid, and when money can move.

The web app cannot bypass those rules. It can only submit transactions that the program accepts.

PDA means Program Derived Address. It is a deterministic address controlled by a Solana program, not by a normal private key.

JomPaySol uses PDAs for vaults, contributor records, and recipient records so the same creator, vault ID, participant, and program ID always derive the expected account addresses.

A token mint identifies which SPL token the vault uses. For example, devnet USDC has a different mint address from mainnet USDC.

The app lets users choose a currency like USDC or USDT, then uses the configured mint internally.

An associated token account is the standard token holding account for one wallet and one token mint. If a wallet has never received that token before, the token account may not exist yet.

The app uses idempotent token account creation so it can safely create the account if missing, or reuse it if it already exists.

Use the app's payment, funding, claim, refund, release, and return actions instead. Direct transfers to a vault token account are not counted as assigned deposits or claims.

If extra tokens are sent directly by mistake, an operator can trigger a constrained sweep after the vault reaches an eligible terminal state. The program only sweeps unaccounted excess and enforces the fixed destination on-chain.

The hosted hackathon setup uses Turso for off-chain metadata. Local development can still use the JSON file driver by setting JOMPAYSOL_STORAGE_DRIVER=json.

Turso stores titles, descriptions, participant labels, invite links, creator wallet, token selection, vault IDs, and transaction signatures. Balances, claims, releases, and refunds should still be treated as on-chain state.

The chain is good for authoritative payment state, but not ideal for UI labels and demo-friendly descriptions. Metadata stores human-friendly fields like the vault title, participant names, and generated links.

If metadata and chain state ever disagree, the on-chain state should win for money movement.

It reads the vault, contributor, and recipient accounts from the configured RPC. It shows live status, deposited amount, claimed or released amount, remaining amount, and participant-specific state.

This is separate from the metadata status pill, which is useful for the UI but not the final source of truth.

Existing local metadata can be migrated with npm run migrate:turso after TURSO_DATABASE_URL and TURSO_AUTH_TOKEN are set.

The migration is safe to rerun. It upserts vaults and participants, ignores duplicate signatures, and leaves apps/web/data/vaults.json untouched as a backup.

Next.js Server Components can cache fetch calls. The Turso client uses HTTP under the hood, so database requests are forced to no-store to avoid stale vault detail pages after migrations or writes.

This keeps the dashboard and individual vault pages consistent during demos.

For ClaimPay, claimed payouts count as released funds. When every assigned payout has been claimed, the vault reaches the Released state.

For GroupPay, Released means the creator sent the fully funded vault to the vendor.

It usually means a required on-chain account does not exist on the current network. A common case is a new wallet with 0 devnet SOL. Until it has SOL, it may not exist as a funded system account and cannot pay fees or create token accounts.

It can also mean the vault was created on a different network or program ID than the app is currently using.

The recipient already claimed their payout. The program blocks a second claim, and the app should show the claim as complete.

For GroupPay, the contributor wallet may not have enough selected SPL token to pay their assigned share. For ClaimPay creation, the creator may not have enough selected SPL token to fund the vault.

SOL balance alone is not enough. The wallet needs both transaction-fee SOL and the selected token balance when sending token funds.

Payment and claim links are wallet-specific. If the connected wallet does not match the participant wallet stored for that link, the app blocks the transaction before wallet approval.

If the vault was created with a .sol name, the stored participant wallet is the address that name resolved to at creation time.

The app only accepts registered .sol names that resolve to a Solana public key. Typos, unregistered names, stale records, or SNS RPC issues can cause resolution to fail.

If that happens, paste the wallet address directly or try again with a configured SNS RPC endpoint.

The metadata exists, but the Solana account could not be read from the configured RPC. Check whether you are on devnet or localnet, whether the program ID matches the deployed program, and whether the vault was actually created successfully.

Not yet. The current goal is MVP testing on devnet or localnet. It proves the core GroupPay and ClaimPay flows, wallet transaction building, Turso-backed metadata, and on-chain state reading.

Before real-money launch, it needs indexing, security review, CI, better RPC infrastructure, program upgrade controls, legal review, and more robust monitoring.

Use Turso or another durable hosted database for metadata and participants. Use chain reads or indexed chain data for financial state.

The local JSON driver should stay limited to offline demos and local development because deployment filesystems are not a durable application database.

An indexer should read vault, contributor, and recipient accounts by program ID, reconcile transaction signatures, and compute dashboard state after refresh.

Polling can work first. Helius webhooks or another event pipeline can come later.

No. The frontend only shows configured tokens, and the on-chain program rejects new vaults whose mint is not in the program config allowlist.

The allowlist is managed after deployment by the configured program config authority. That authority can be rotated after initialization, for example to a multisig or operational admin wallet.