This repository contains the on-chain Anchor program for the Galaxy Facilitator Protocol, a non-custodial system for x402-style metered billing on Solana. [1, 2, 3, 4, 5, 6, 7, 8, 9]
It enables users to deposit funds into a personal vault and delegate spending authority to one or more "agents" (e.g., API servers, AI agents) with specific, on-chain enforced budgets. This allows for high-frequency, off-chain authorized payments without requiring the user to sign every transaction.
The protocol operates on a "leashed trust" model. The user (Authority) provisions a budget, and the agent (Server) can draw from that budget up to the specified limit. The user always retains custody of their funds.
-
PaymentVault(PDA)- Seeds:
[b"vault", authority.key()] - Description: This is the user's master vault. It is a Program-Derived Address that serves as the central authority for the user's funds. It owns the
TokenVault. [10, 11, 12]
- Seeds:
-
TokenVault(ATA)- Authority: The
PaymentVaultPDA. - Description: This is an Associated Token Account that holds the user's actual SPL tokens (e.g., USDC). All agent spending is drawn from this single account. [13, 14, 15]
- Authority: The
-
AgentPermission(PDA)- Seeds:
[b"permission", authority.key(), agent.key()] - Description: This is the "leash." It is a separate metadata PDA that links a user (
authority) to a specificagent. It stores thebudget(total allowance) andspent(total consumed) for that agent. This account is the core of the multi-agent budget system. [16]
- Seeds:
The system is designed for a clean separation of responsibilities between the user and the agent.
- Funding (User): A user calls
initialize_vaultone time. This creates theirPaymentVault, the associatedTokenVault, and makes an initial deposit. [10, 17] - Delegation (User): The user calls
authorize_agentfor each service (agent) they wish to use. This instruction creates (or updates) anAgentPermissionPDA, setting abudgetfor that specific agent. - Spending (Agent):
- A user authenticates with the agent's off-chain server (e.g., by signing an off-chain message). [18, 19, 20]
- The agent's server, now authorized, calls
spend_from_vaultto request payment for its service. - The on-chain program verifies:
- The signer is the
agentspecified in theAgentPermissionPDA. [21, 22, 23, 24] - The requested
amountis within thebudget - spentlimit.
- The signer is the
- If valid, the program executes a CPI transfer from the user's
TokenVault(signed by thePaymentVaultPDA) to the agent's treasury wallet. [10, 25, 26]
- Revoking (User): The user calls
revoke_agentto destroy an agent'sAgentPermissionaccount, instantly revoking all spending privileges and refunding the account's rent. - Exiting (User): The user calls
withdraw_and_closeat any time. This is the non-custodial exit ramp. It transfers 100% of the remaining funds from theTokenVaultback to the user and closes both thePaymentVaultandTokenVaultaccounts. [27, 28, 29, 30]
1. initialize_vault(ctx, amount: u64)
- Signer:
authority(User) - Description: Creates the user's master
PaymentVaultand itsTokenVault. Deposits an initialamountof tokens.
2. authorize_agent(ctx, budget: u64)
- Signer:
authority(User) - Description: Creates or updates an
AgentPermissionPDA for a specificagent. Sets the totalbudgetthis agent is authorized to spend. Usesinit_if_neededfor seamless creation or updates. [22]
3. revoke_agent(ctx)
- Signer:
authority(User) - Description: Closes an
AgentPermissionaccount, revoking theagent's spending rights and refunding the account's rent to theauthority.
4. withdraw_and_close(ctx)
- Signer:
authority(User) - Description: The non-custodial exit. Withdraws all remaining funds from the
TokenVaultand closes the master vault accounts, refunding all rent.
5. spend_from_vault(ctx, amount: u64)
- Signer:
agent(Server) - Description: Called by the agent to request payment. The program validates the request against the
AgentPermissionbudget and, if successful, transfersamountof tokens from the user'sTokenVaultto the agent'streasury_token_account.
Security is enforced through Anchor's constraint system, preventing unauthorized access or spending. [31, 32]
has_one: This is the primary constraint.spend_from_vaultuseshas_one = authorityandhas_one = agenton theAgentPermissionaccount. This cryptographically ensures that theagentsigning the transaction is the exact agent authorized by theauthority(user) for that specific permission account. [21, 22, 23, 24]seeds&bump: All PDA accounts (PaymentVault,AgentPermission) are validated with their seeds and canonical bump. This prevents PDA substitution attacks, where an attacker might pass a malicious account. [16, 33]- Budget Enforcement: All spending logic is on-chain and atomic. The check for
amount <= budget - spentand the update tospenthappen in the same instruction, making it impossible for an agent to overspend their budget. - Non-Custodial: At no point does the agent or the protocol take custody of the user's funds. The
withdraw_and_closeinstruction guarantees the user can reclaim their entire balance at any time. [30]
- (https://www.rust-lang.org/tools/install)
- (https://docs.solana.com/cli/install)
- Anchor Framework (
avm install latest&&avm use latest) [34]
Compile the program and generate the IDL (Interface Definition Language):
anchor buildThe IDL will be generated at target/idl/galaxy_facilitator.json.
Run the local test suite:
anchor test-
Configure your Solana CLI for the desired cluster (e.g.,
devnetormainnet-beta):solana config set --url devnet -
Ensure your deployment wallet is funded.
solana airdrop 2 # (Devnet only) -
Deploy the program:
anchor deploy
The anchor deploy command will output a new Program ID.
- Update
lib.rs: Copy the new Program ID and paste it into thedeclare_id!(...)macro at the top ofprograms/galaxy_facilitator/src/lib.rs. - Update
Anchor.toml: Paste the new Program ID into yourAnchor.tomlfile, under the cluster you deployed to (e.g.,[programs.devnet]).
Re-run anchor build one final time to incorporate the new Program ID into the IDL.
This on-chain program serves as the trust layer. The "Galaxy Facilitator" server is the off-chain component responsible for verifying user authorization (e.g., via signMessage) and calling the spend_from_vault instruction.
The server will use the generated target/idl/galaxy_facilitator.json and the @coral-xyz/anchor Typescript library to build, sign (as the agent and feePayer), and send transactions. [35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47]