GitSafe Documentation
GitSafe launches on Solana Mainnet. Program ID: GSaFe11111xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Verified on Solscan. Apache 2.0 license. All bot commands will execute on mainnet at launch.
GitSafe is the secure on-chain bank inside your GitHub, built on Solana. It gives every user a personal vault anchored to their GitHub identity, lets teams manage project workspaces and bounties entirely through issue comments, enables in-vault token swaps via Jupiter, and protects everything with soul-bound safeTokens that no AI agent, bot, or third party can drain. There is no wallet app to install, no seed phrase to manage, and no KYC.
Personal vault on Solana
Deposit USDC, SOL, or any SPL token. Assets are minted 1:1 as soul-bound safeTokens held in a Program Derived Address (PDA) anchored to your GitHub identity.
Projects, bounties, and auto-pay
Create project workspaces, assign bounties to contributors, and release payments automatically when a pull request merges — all from a GitHub issue comment.
Swap tokens inside your vault
Exchange safeTokens without leaving GitSafe. Underlying assets are routed through Jupiter aggregator and re-minted as the output safeToken in a single atomic transaction.
Bot-safe by design
safeTokens have no transfer or approve instruction. A compromised AI agent cannot drain your vault even with a valid signature. Soul-bound means zero attack surface.
Supported assets
| Asset | SafeToken | Network | Status |
|---|---|---|---|
| USDC | safeUSDC | Solana Mainnet | Supported |
| SOL | safeSOL | Solana Mainnet | Supported |
| USDT | safeUSDT | Solana Mainnet | Supported |
| JTO | safeJTO | Solana Mainnet | Supported |
| Any SPL Token | safeXXX | Solana Mainnet | Via governance |
Platform properties
Every vault is permanently bound to a GitHub Permanent User ID — an immutable integer assigned at account creation. Renaming a GitHub username does not affect vault ownership.
safeTokens are SPL tokens with the transfer authority permanently revoked on-chain. No approve, no transferFrom, no drain path — not even for the program deployer.
All vault operations, project creation, bounty assignment, and swaps are triggered by @gitsafebot comments in GitHub issues or PRs. Any language accepted.
The GitSafe relayer wallet pays all Solana transaction fees (~$0.00025 per tx). Users never need to hold SOL for gas.
Humans, bots, and autonomous agents can all operate a vault. The vault is anchored to a GitHub identity, not to whether the operator is human or automated.
Every operation is recorded on Solana Mainnet (~400ms finality). The bot posts a receipt with tx signature, Solscan link, amounts, and fee to the same GitHub issue.
Assets are held in PDA smart accounts, not by GitSafe. The team cannot access or freeze user funds. An emergency exit is available after 6 months of vault inactivity.
How It Works
Every GitSafe action follows the same authenticated pipeline: from a GitHub comment to on-chain execution on Solana. Five steps, roughly 1–2 seconds end-to-end. The user never touches a wallet, signs a transaction manually, or pays gas.
Command pipeline
GitHub Issue Comment
@gitsafebot deposit 10 USDCBot Service
reads sender.id (permanent GitHub User ID)Claude Haiku
returns JSON intent with confidence scoreRelayer
signs intent + broadcasts via deployer walletGitSafe Solana Program
executes on-chain, emits eventsBot replies to issue
tx signature + Solscan link + amountsSecurity checks
Before any instruction is executed, the pipeline performs these checks in order:
- Webhook signature — HMAC-SHA256 with the GitHub App secret. Any request with an invalid signature is rejected immediately.
- Permanent User ID — The bot reads
sender.idfrom the webhook payload, notsender.login. Username changes cannot hijack a vault. - AI confidence — If Claude Haiku's confidence score falls below the threshold, the bot replies asking for clarification. No transaction is broadcast.
- On-chain verification — The Solana program re-checks manager permissions and vault ownership before executing any instruction. Application-level checks are not the last line of defence.
- Idempotency key — Each webhook event carries a unique delivery ID. The relayer deduplicates against a recent-events cache to prevent double-execution.
Solana Program architecture
The GitSafe program is written in Anchor. It manages three account types:
| Account | Seeds | Purpose |
|---|---|---|
| Vault | [b"vault", github_uid] | Holds safeToken balances |
| Project | [b"project", vault_key, name_hash] | Budget + task registry |
| Task | [b"task", project_key, task_id] | Bounty escrow + assignee |
Getting Started
Get your GitSafe vault running in under two minutes. No wallet setup, no seed phrases, no gas. Just install the GitHub App and start commenting.
Step 1 — Install the GitHub App
Go to github.com/apps/gitsafebot and click Install. Grant access to the repositories where you want to use GitSafe. The bot will post a confirmation comment in your first enabled repository.
Step 2 — Create your vault
Open any issue in an enabled repo and comment:
@gitsafebot create vault
The bot deploys a PDA vault on Solana Mainnet anchored to your GitHub Permanent User ID. This happens once per user. Receipt includes your vault address and a Solscan link.
Step 3 — Deposit funds
@gitsafebot shield 50 USDC
The bot provides a deposit address. Send USDC (SPL) to that address. Once the transaction confirms, the bot mints safeUSDC 1:1 into your vault and posts a receipt.
Step 4 — Check your balance
@gitsafebot balance
The bot replies with your current safeToken balances and total vault value in USD.
All available commands
gitShield — Deposit
gitShield is the deposit operation. It converts external SPL tokens into soul-bound safeTokens held inside your vault PDA. The name comes from the idea of "shielding" real assets inside the GitSafe protocol.
Command syntax
@gitsafebot shield <amount> <token>
# Examples
@gitsafebot shield 100 USDC
@gitsafebot shield 0.5 SOL
@gitsafebot shield 1000 USDT
The bot replies with a deposit address specific to your vault. Send the exact token amount to that address from any Solana wallet. Once confirmed (usually 1–2 slots, ~400ms), the bot mints the equivalent safeTokens 1:1 into your vault and posts a receipt.
What happens on-chain
- The relayer calls the
shieldinstruction on the GitSafe program. - The program verifies the inbound SPL transfer was received at the vault's deposit escrow PDA.
- The program mints the equivalent amount of the safeToken to the user's vault PDA.
- The inbound tokens are locked in the escrow — they back the safeToken supply 1:1 at all times.
- An event is emitted; the bot reads it and posts the receipt comment with the Solscan link.
Supported assets
| Token | Mint address | safeToken |
|---|---|---|
| USDC | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v | safeUSDC |
| SOL (wSOL) | So11111111111111111111111111111111111111112 | safeSOL |
| USDT | Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB | safeUSDT |
| JTO | jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL | safeJTO |
Notes
- There is no minimum deposit. Any amount is accepted.
- Deposits are irrevocable via standard SPL transfer once confirmed. Use gitUnshield to withdraw.
- The deposit escrow address changes per session. Always use the address the bot provides in the current comment thread.
- Native SOL is automatically wrapped to wSOL by the relayer before shielding.
gitUnshield — Withdraw
gitUnshield is the withdrawal operation. It burns safeTokens from your vault and transfers the equivalent real SPL tokens to a destination Solana address you specify.
Command syntax
@gitsafebot unshield <amount> <token> <solana_address>
# Examples
@gitsafebot unshield 50 USDC 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
@gitsafebot unshield 0.1 SOL 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
What happens on-chain
- The relayer calls the
unshieldinstruction. - The program verifies the caller is the vault owner (matched via GitHub User ID in PDA seeds).
- The safeToken amount is burned from the vault PDA.
- The equivalent SPL tokens are released from the escrow PDA and transferred to the destination address.
- A 0.2% fee is deducted from the withdrawn amount and sent to the fee collector PDA.
Two-step commit/reveal
For amounts above 500 USDC, GitSafe uses a commit/reveal mechanism to prevent front-running and MEV attacks:
- The relayer commits a hash of the withdrawal details on-chain.
- After a 1-slot delay, the relayer reveals and executes the withdrawal.
- If the reveal does not match the commit, the program reverts.
This adds one additional slot (~400ms) to large withdrawals but ensures the destination address and amount cannot be intercepted or replaced.
Recovery address
Each vault has an optional recovery address. If set, large withdrawals above the configured threshold can only go to the recovery address. This limits the blast radius of a compromised bot token.
@gitsafebot set recovery 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
gitSwap — In-Vault Swap
gitSwap lets you exchange one safeToken for another without leaving your vault. The underlying SPL tokens are routed through Jupiter aggregator for best execution price, then re-minted as the target safeToken — all in a single atomic transaction.
Command syntax
@gitsafebot swap <amount> <from_token> for <to_token>
# Examples
@gitsafebot swap 100 USDC for SOL
@gitsafebot swap 0.5 SOL for USDC
@gitsafebot swap 200 USDT for JTO
Execution flow
- The bot queries Jupiter API for the best route and slippage estimate.
- The bot replies with a quote: expected output, price impact, and estimated fee. You confirm by replying yes or confirm.
- The relayer calls
swapon the program with the Jupiter route encoded as calldata. - The program unshields the source token, routes through Jupiter, and re-shields the output token — all atomically.
- A 0.2% GitSafe fee is applied in addition to Jupiter's protocol fee.
Slippage
Default slippage tolerance is 0.5%. You can override it per swap:
@gitsafebot swap 100 USDC for SOL slippage 1%
If actual slippage exceeds the tolerance, the transaction is reverted and you keep your original tokens.
Transfer — Vault to Vault
Transfer moves safeTokens directly from your vault to another GitSafe user's vault. Because safeTokens are soul-bound and cannot be transferred via standard SPL, transfers go through the GitSafe program which burns from the sender and mints to the receiver.
Command syntax
@gitsafebot transfer <amount> <token> to @github_username
# Examples
@gitsafebot transfer 50 USDC to @alice
@gitsafebot transfer 0.1 SOL to @bob
How it works
- The bot resolves
@aliceto their GitHub Permanent User ID. - The program verifies the recipient has an active vault PDA on-chain.
- The safeToken amount is burned from the sender's vault.
- An equivalent amount is minted into the recipient's vault.
- A 0.2% fee is applied and sent to the fee collector.
- Both sender and recipient receive a receipt comment in the thread.
Requirements
- The recipient must have an existing vault (created via
@gitsafebot create vault). - Transfers cannot be reversed. Double-check the username before confirming.
- Maximum transfer per transaction: 10,000 USDC equivalent. Larger amounts require multiple transactions.
Create a Project
A Project is a named workspace with a locked budget pool. Managers create projects, allocate a budget from their vault, and then assign portions of that budget as bounties on individual issues. When a PR merges, the payment is released automatically.
Command syntax
@gitsafebot create project "<name>" with <amount> <token> budget
# Example
@gitsafebot create project "Mobile App v2" with 500 USDC budget
What happens on-chain
- A
ProjectPDA is created with seeds[b"project", vault_key, name_hash]. - The specified budget is transferred from your vault's
safeUSDCbalance into the project escrow PDA. - You are registered as the project manager. You can add additional managers with the
add managercommand. - A 0.5% install fee is deducted from the budget and sent to the treasury (see Install Fee section).
Managing the project
# Add a co-manager @gitsafebot add manager @username to project "Mobile App v2" # Check project budget @gitsafebot project "Mobile App v2" balance # Top up budget @gitsafebot add 200 USDC to project "Mobile App v2" # Reclaim unspent budget (manager only) @gitsafebot reclaim project "Mobile App v2"
Assign Tasks & Bounties
Once a project is created, managers can assign individual GitHub issues as tasks with a bounty attached. The bounty is held in escrow until the linked pull request merges.
Command syntax
# Assign the current issue @gitsafebot assign this to @contributor with 45 USDC bounty # Assign a specific issue by number @gitsafebot assign issue #23 to @contributor with 45 USDC bounty from project "Mobile App v2" # Assign with deadline @gitsafebot assign this to @contributor with 45 USDC bounty deadline 2025-09-01
Escrow mechanics
- A
TaskPDA is created:[b"task", project_key, task_id]. - The bounty amount is moved from the project escrow into the task escrow.
- The assignee's GitHub User ID is stored in the task account.
- Funds are locked until the task is closed by a PR merge or cancelled by a manager.
Cancelling a task
# Unassign and return funds to project budget
@gitsafebot unassign this task
Only a project manager can cancel a task. The bounty is returned to the project escrow PDA.
Auto-Pay on PR Merge
When a pull request that closes an assigned issue is merged, GitSafe automatically detects the event and releases the bounty to the contributor's vault — no manual action required.
How the detection works
- The GitHub App listens for
pull_request.closedwebhook events wheremerged: true. - The bot checks the PR body and commits for closing keywords: closes #N, fixes #N, resolves #N.
- For each matched issue, the bot looks up the on-chain task PDA.
- The relayer calls
release_bountyon the program with the PR merge event as proof. - The program verifies the task is still open, then mints the bounty safeTokens into the contributor's vault.
- A 0.2% fee is deducted before release. The bot posts receipts in both the issue and the PR.
Edge cases
| Scenario | Outcome |
|---|---|
| PR merged, contributor has no vault | Funds held in escrow for 30 days; contributor can claim by creating a vault |
| PR closed without merge | No payment; funds remain in task escrow |
| Multiple PRs close same issue | First merge triggers payment; subsequent events are no-ops |
| Assignee GitHub account deleted | Manager can reclaim after 90 days via @gitsafebot reclaim task #N |
Install Fee & Treasury
When a project is created, a one-time 0.5% install fee is deducted from the initial project budget and sent to the GitSafe treasury PDA. This fee supports ongoing development, relayer infrastructure, and the security audit fund.
Fee example
| Action | Budget | Install fee (0.5%) | Available budget |
|---|---|---|---|
| Create project with 1000 USDC | 1000 USDC | 5 USDC | 995 USDC |
| Create project with 500 USDC | 500 USDC | 2.50 USDC | 497.50 USDC |
Treasury PDA
Install fees and a portion of protocol fees accumulate in the GitSafe treasury PDA. Treasury funds are governed by the GitSafe DAO and used for:
- Relayer gas top-ups (SOL for transaction fees)
- Ongoing security audits
- Protocol development grants
- Bug bounty payouts
Top-ups do not incur install fees
Adding additional budget to an existing project does not trigger another install fee. Only the initial project creation incurs the 0.5% charge.
Identity Anchoring
GitSafe anchors every vault to a GitHub Permanent User ID — an immutable integer assigned by GitHub at account creation time. This is the core security primitive that makes GitSafe safe for AI agents.
Why Permanent User ID, not username
GitHub usernames can be changed, transferred, or reclaimed. If vault ownership were tied to a username, an attacker could rename their account to a target username after the original owner renamed theirs, then claim ownership of the vault.
The Permanent User ID cannot be changed by the user, cannot be transferred, and cannot be claimed by another account. It is the only GitHub identity primitive safe to use as an on-chain key.
How the ID becomes a PDA
// Vault PDA derivation (Anchor) let (vault_pda, bump) = Pubkey::find_program_address( &[b"vault", &github_uid.to_le_bytes()], &program_id, );
The same Permanent User ID always produces the same vault address on Solana. There is no mapping table and no registry — the address is deterministic.
Webhook verification
The GitHub webhook payload includes sender.id (the Permanent User ID) alongside sender.login (the username). The bot exclusively uses sender.id to look up vaults. Username spoofing via a renamed account is structurally impossible in this model.
Soul-Bound Tokens
safeTokens are SPL tokens whose transfer authority is permanently set to the GitSafe program PDA. No external wallet, agent, or attacker can initiate a transfer. Only the GitSafe program can move them — and only via verified instructions.
How they differ from standard SPL tokens
| Property | Standard SPL | safeToken |
|---|---|---|
| Transfer | Any holder can transfer | Only GitSafe program via verified instruction |
| Approve / Delegate | Supported | Not supported — no delegate authority |
| Burn | Token owner | GitSafe program only (on gitUnshield) |
| Mint | Mint authority | GitSafe program only (on gitShield) |
| DeFi composability | Full | None by design — vault-internal only |
Attack scenarios eliminated
- Phishing signatures — There is no transaction to sign that moves safeTokens. A phishing site cannot construct a valid transfer.
- Compromised AI agent — Even with full bot access and a valid relayer key, an agent cannot call a transfer instruction on safeTokens directly.
- Malicious approve — No approve function exists. There is no attack surface for draining via a delegate.
- Rug by deployer — The program upgrade authority will be revoked after audit. Even the GitSafe team cannot drain vaults.
Recovery
GitSafe provides two recovery mechanisms to ensure users are never permanently locked out of their vault.
Recovery address
You can designate a recovery address — any Solana wallet you control. If you lose access to the GitHub account that owns your vault, the recovery address can initiate a time-locked vault migration.
@gitsafebot set recovery 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
Recovery is time-locked for 72 hours after initiation. During this window, the original vault owner can cancel the recovery by commenting in any enabled repository. This prevents an attacker who compromises your recovery wallet from immediately draining funds.
Key rotation
If you suspect your GitHub account is compromised, you can rotate the signing key used by the relayer for your vault:
@gitsafebot rotate signing key
This generates a new relayer sub-key pair for your vault and stores the public key on-chain. Old keys are immediately revoked.
Emergency exit
After 6 months of vault inactivity, the program allows the recovery address to withdraw all assets without the standard relayer flow. This ensures funds are never permanently stranded if GitSafe shuts down or the bot becomes unavailable.
The emergency exit bypasses the GitSafe bot entirely and interacts with the on-chain program directly via any Solana wallet client.
Fee Structure
GitSafe charges a flat 0.2% protocol fee on value-moving operations. There are no subscription fees, no monthly charges, and no hidden costs. The relayer pays all Solana network fees on behalf of users.
| Operation | Protocol Fee | Solana Gas | Notes |
|---|---|---|---|
| gitShield (deposit) | 0% | Covered by relayer | No fee on deposits |
| gitUnshield (withdraw) | 0.2% | Covered by relayer | Deducted from withdrawn amount |
| gitSwap | 0.2% + Jupiter fee | Covered by relayer | Jupiter fee varies (~0.1–0.3%) |
| Transfer (vault-to-vault) | 0.2% | Covered by relayer | Deducted from sender |
| Bounty release | 0.2% | Covered by relayer | Deducted from bounty |
| Project creation | 0.5% (install fee) | Covered by relayer | One-time, from budget |
| Balance check | 0% | Covered by relayer | Read-only, no fee |
Fee example — bounty workflow
# Manager creates project with 1000 USDC Install fee: 0.5% = 5 USDC → available budget: 995 USDC # Manager assigns 100 USDC bounty 100 USDC escrowed in task PDA # PR merged, bounty released to contributor Protocol fee: 0.2% = 0.20 USDC Contributor receives: 99.80 USDC
Relayer
The relayer is a trusted service operated by GitSafe that bridges GitHub webhook events to Solana transactions. It holds a funded Solana wallet that signs and broadcasts all on-chain instructions on behalf of users.
Why a relayer?
Solana requires all transactions to be signed by a funded keypair that pays the transaction fee (~0.000005 SOL). Since users interact via GitHub comments and may not hold any SOL, the relayer acts as the transaction fee payer and broadcaster, enabling a gasless experience.
What the relayer can and cannot do
| Action | Relayer can? |
|---|---|
| Call gitShield, gitUnshield, transfer on behalf of a user | ✓ Yes (with verified intent) |
| Drain a user's vault unilaterally | ✗ No — program requires GitHub-ID-verified intent |
| Transfer safeTokens directly (SPL transfer) | ✗ No — transfer authority is the program PDA, not relayer |
| Cancel or delay a transaction | ✓ Yes — relayer can choose not to broadcast |
Relayer uptime and fallback
The GitSafe relayer targets 99.9% uptime. If the relayer is unavailable, users can interact with the program directly using the CLI (gitsafe) or any Solana wallet with the IDL loaded. The emergency exit path is always available on-chain regardless of relayer status.
Fee Collector
Protocol fees accumulate in the fee collector PDA, a program-derived address controlled exclusively by the GitSafe DAO multisig. Fees are denominated in the token being transacted (USDC fees stay as USDC, SOL fees stay as SOL).
Fee collector address
// Fee collector PDA derivation let (fee_collector, _) = Pubkey::find_program_address( &[b"fee_collector"], &program_id, );
Fee distribution
| Destination | Share | Purpose |
|---|---|---|
| Treasury PDA | 60% | Development, audits, grants |
| Relayer fund | 30% | SOL top-ups for transaction fees |
| Bug bounty fund | 10% | Security researcher rewards |
Distribution is governed by the GitSafe DAO and can be adjusted via on-chain governance vote. All fee flows are publicly verifiable on Solscan.
AI Agent Wallet
GitSafe is the only on-chain bank account designed for AI agents. Because safeTokens are soul-bound and the program enforces permissions at the instruction level, you can give an agent full bot access without risking vault drainage.
How agent access works
An AI agent operates through the same IssueOps interface as a human: by commenting @gitsafebot <command> in GitHub issues. The agent must have a GitHub token with comment permissions on the repository.
# Typical agent workflow # 1. Agent detects a completed task # 2. Agent comments to release payment @gitsafebot assign issue #47 to @contributor with 30 USDC bounty # 3. PR merges → auto-pay fires # 4. Agent checks project balance @gitsafebot project "Sprint 3" balance
Security properties for agents
- No drain path — safeTokens cannot be transferred by the agent directly. Even with a stolen GitHub token, there is no instruction to call.
- Rate limiting — The bot enforces per-user command rate limits. A runaway agent cannot spam transactions.
- Manager-only operations — Budget allocation and project creation require manager role. Give agents contributor-level access only if they should not control budget.
- Confidence threshold — Claude Haiku's confidence score must exceed 0.92 for any financial operation. Ambiguous agent commands are rejected with a clarification request.
Recommended agent pattern
// Pseudocode: agent bounty automation async function onPRMerge(pr) { const issue = await getLinkedIssue(pr); const contributor = issue.assignee.login; const bounty = await estimateBounty(issue.complexity); // Agent posts the command — GitSafe program handles payment await ghComment(issue.number, `@gitsafebot assign this to @${contributor} with ${bounty} USDC bounty` ); }
Trading Bot Integration
GitSafe vaults can serve as the treasury for autonomous trading bots. The bot can execute swaps and check balances, but cannot drain the vault or transfer funds to external addresses without a verified GitHub identity check.
Setup
- Create a dedicated GitHub account for your bot (e.g.
myproject-treasury-bot). - Create a vault for that account:
@gitsafebot create vault. - Fund the vault via gitShield.
- Give the bot a GitHub token with
issues:writeandpull_requests:writepermissions on the repo. - The bot comments
@gitsafebot swap ...to rebalance.
Rate limits
| Operation | Limit |
|---|---|
| Swaps | 10 per hour per vault |
| Balance checks | Unlimited |
| Transfers | 5 per hour per vault |
| Withdrawals | 3 per day per vault |
Webhook integration
If you run your own bot service, you can subscribe to GitSafe program events via a Solana WebSocket connection and react to on-chain state changes without polling GitHub comments:
const ws = new WebSocket('wss://api.mainnet-beta.solana.com'); ws.send(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'logsSubscribe', params: [{ mentions: ['GSaFe11111xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'] }] }));
Contract Reference
The GitSafe program is written in Rust using the Anchor framework. All accounts use PDA derivation. The program is open-source under Apache 2.0.
Program ID
GSaFe11111xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Instructions
| Instruction | Accounts | Description |
|---|---|---|
create_vault | vault, github_uid, payer | Deploy vault PDA for a GitHub User ID |
shield | vault, deposit_escrow, safe_token_mint, user_ata | Deposit SPL token, mint safeToken |
unshield | vault, deposit_escrow, safe_token_mint, destination | Burn safeToken, release SPL token |
swap | vault, jupiter_program, route_accounts[] | Atomic in-vault swap via Jupiter |
transfer | sender_vault, recipient_vault, safe_token_mint | Burn-and-mint vault-to-vault transfer |
create_project | vault, project, fee_collector | Create project PDA with budget |
create_task | project, task, assignee_vault | Create task PDA with bounty escrow |
release_bounty | task, project, assignee_vault, fee_collector | Release bounty on PR merge |
set_recovery | vault, recovery_address | Set or update recovery address |
recover | vault, recovery_address, destination | Emergency withdraw (72h timelock) |
Account structures
#[account] pub struct Vault { pub github_uid: u64, // GitHub Permanent User ID pub bump: u8, // PDA bump pub recovery: Option<Pubkey>, // Optional recovery address pub created_at: i64, // Unix timestamp pub last_active: i64, // For emergency exit timer } #[account] pub struct Project { pub vault: Pubkey, // Owner vault pub name_hash: [u8; 32], // SHA256 of project name pub token_mint: Pubkey, // Budget token (e.g. USDC) pub budget: u64, // Remaining budget pub managers: Vec<u64>, // GitHub UIDs of managers } #[account] pub struct Task { pub project: Pubkey, // Parent project pub task_id: u64, // GitHub issue number pub assignee_uid: u64, // Assignee GitHub UID pub bounty: u64, // Escrowed amount pub closed: bool, // Released or cancelled }
Security for Agents
GitSafe is the only on-chain bank where giving an AI agent vault access does not require trusting the agent's integrity. Security is enforced at the Solana program level, not at the application level.
Threat model
| Threat | Traditional wallet | GitSafe |
|---|---|---|
| Compromised agent private key | Full vault drain possible | No drain path — safeTokens not transferable by key |
| Phishing via approve | Vault drained via delegated spend | No approve instruction exists |
| Malicious swap route | Agent can call any DEX | Swap routes validated by program against allowlist |
| Unauthorized withdrawal | Any signed tx drains | GitHub User ID check in PDA derivation |
| Runaway agent (infinite loop) | Drains all gas + funds | Rate limiter in bot; gas paid by relayer not agent |
Recommended permissions for agents
- Contributor role only — unless the agent needs to manage budgets, do not add it as a project manager.
- Separate vault per agent — create a dedicated GitHub account per agent and fund it with limited budget.
- Set a recovery address — point to a hardware wallet you control. If the agent misbehaves, recovery gives you a time-locked escape.
- Monitor Solscan events — subscribe to program events for the agent's vault to detect anomalies in real time.
CLI (gitsafe)
The gitsafe CLI lets you interact with your vault directly from the terminal, without going through GitHub issue comments. Useful for power users, CI/CD pipelines, and emergency access when the bot is unavailable.
Installation
# Via npm npm install -g @gitsafe/cli # Via Homebrew (macOS) brew install gitsafe-cli # Verify gitsafe --version
Authentication
# Authenticate with GitHub (opens browser) gitsafe auth login # Or provide a token directly gitsafe auth login --token ghp_xxxxxxxxxxxx
Commands
Config file
# ~/.gitsafe/config.yaml rpc_url: https://api.mainnet-beta.solana.com network: mainnet github_token: ghp_xxxxxxxxxxxx default_slippage: 0.5
SDK (@gitsafe-agent/sdk)
The TypeScript SDK lets you integrate GitSafe vault operations into your own applications, bots, and agents without going through GitHub issue comments.
Installation
npm install @gitsafe-agent/sdk @solana/web3.js
Initialization
import { GitSafeClient } from '@gitsafe-agent/sdk'; import { Connection, clusterApiUrl } from '@solana/web3.js'; const client = new GitSafeClient({ connection: new Connection(clusterApiUrl('mainnet-beta')), githubToken: process.env.GITHUB_TOKEN, relayerUrl: 'https://relay.gitsafe.io', });
Vault operations
// Get vault address for a GitHub user const vault = await client.vault.getAddress('octocat'); // Fetch balances const balances = await client.vault.getBalances('octocat'); // → { safeUSDC: 150.00, safeSOL: 0.42, usdValue: 217.80 } // Shield (deposit) const tx = await client.vault.shield({ user: 'octocat', amount: 50, token: 'USDC', }); // Unshield (withdraw) const tx = await client.vault.unshield({ user: 'octocat', amount: 25, token: 'USDC', destination: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU', }); // Swap via Jupiter const quote = await client.vault.getSwapQuote({ from: 'USDC', to: 'SOL', amount: 100 }); const tx = await client.vault.swap({ user: 'octocat', quote });
Project operations
// Create project await client.project.create({ manager: 'octocat', name: 'Sprint 4', budget: 500, token: 'USDC', }); // Assign bounty await client.task.assign({ project: 'Sprint 4', issueNumber: 47, assignee: 'alice', bounty: 45, token: 'USDC', }); // Listen for PR merge events → auto release client.tasks.onMerge(async (event) => { await client.task.release(event.taskId); });
Glossary
| Term | Definition |
|---|---|
| safeToken | A soul-bound SPL token minted 1:1 against a deposited asset. Transfer authority is set to the GitSafe program PDA. Cannot be moved by any external wallet or agent. |
| Vault | A Solana Program Derived Address (PDA) that holds a user's safeToken balances. Derived from the user's GitHub Permanent User ID. |
| PDA | Program Derived Address. A deterministic Solana address derived from seeds and a program ID. Has no private key; only the program can sign for it. |
| gitShield | The deposit operation. Converts external SPL tokens into safeTokens inside the vault. |
| gitUnshield | The withdrawal operation. Burns safeTokens and releases the underlying SPL tokens to a destination address. |
| gitSwap | In-vault token swap routed through Jupiter aggregator. Atomically unshields, swaps, and re-shields. |
| GitHub Permanent User ID | An immutable integer assigned by GitHub at account creation. Cannot be changed by renaming the account. Used as the vault key. |
| Relayer | GitSafe's transaction broadcaster. Pays Solana transaction fees on behalf of users, enabling gasless operation. |
| Project | A named workspace with a locked budget pool. Managers assign bounties from the project budget to individual tasks. |
| Task | A GitHub issue with an assigned contributor and bounty escrowed in a Task PDA. Released when the linked PR merges. |
| IssueOps | The pattern of controlling on-chain operations via GitHub issue comments using a bot mention. |
| Soul-bound | Tokens that cannot be transferred by their holder. Transfer authority belongs exclusively to the issuing program. |
| Commit/reveal | A two-phase on-chain mechanism that prevents front-running large withdrawals by committing a hash before revealing parameters. |
| Recovery address | An optional Solana wallet that can initiate a time-locked vault migration if the owner loses GitHub access. |
| Install fee | A one-time 0.5% fee deducted from a project's initial budget. Funds the GitSafe treasury. |
| Jupiter | Solana's leading DEX aggregator, used by gitSwap to route token exchanges for best price. |
| Anchor | The Rust framework used to write the GitSafe Solana program. Provides account validation, IDL generation, and TypeScript client generation. |
FAQ
Is GitSafe safe to use with an AI agent?
Yes. safeTokens have no transfer or approve instruction. An AI agent with full GitHub bot access and even a compromised relayer key cannot drain your vault. The program enforces ownership at the instruction level — there is simply no function to call that would move your funds without a verified GitHub User ID match.
What happens if GitSafe shuts down?
Your funds are held in on-chain PDAs, not by GitSafe. If GitSafe discontinues operations: (1) the program remains deployed — Solana programs cannot be deleted by their deployer once the upgrade authority is revoked; (2) the CLI and SDK can interact with the program directly without the relayer; (3) the emergency exit path allows recovery via the recovery address after 6 months of inactivity.
Can GitSafe access my funds?
No. The program's upgrade authority will be transferred to the GitSafe DAO multisig after the security audit, and then revoked entirely. After revocation, the team cannot modify the program or access vault funds.
Do I need to hold SOL to use GitSafe?
No. The GitSafe relayer pays all Solana transaction fees (~$0.00025 per transaction) on your behalf. You only need the tokens you want to deposit.
What is the minimum deposit?
There is no minimum deposit amount. Any amount of any supported SPL token is accepted.
Why Solana and not Ethereum or Base?
Solana's transaction costs (~$0.00025 per tx) make automated bounty payments economically viable at any size. On Ethereum mainnet, a $5 bounty could cost $2–10 in gas. Base is cheaper but still an order of magnitude more expensive than Solana. For developer payments that need to scale to hundreds of daily transactions across many repositories, Solana is the only viable option.
Can I use GitSafe without installing the GitHub App?
The GitHub App is required for bot comment parsing and webhook events. However, the CLI and SDK can interact with the Solana program directly without the App for advanced use cases.
What happens if I rename my GitHub username?
Nothing. Your vault is anchored to your GitHub Permanent User ID, not your username. Renaming your account does not affect vault ownership or access.
Is there a maximum vault size?
There is no enforced limit. The program handles arbitrary balances for each supported token. Practical limits are set by available liquidity for gitSwap operations.
How do I report a security vulnerability?
Email security@gitsafe.io with a detailed description. Critical vulnerabilities receive a reward from the bug bounty fund. Do not disclose publicly before we have had 72 hours to respond.
Can I have multiple vaults?
One vault per GitHub account. To manage separate budgets, use the Projects feature — each project has its own escrow PDA with independent accounting.
Roadmap
GitSafe is launching soon on Solana Mainnet. Here is what is planned:
Phase 1 — Foundation (Q3 2025)
- Solana Anchor program deployment
- GitHub App (webhook + AI parser)
- gitShield / gitUnshield (deposit/withdraw)
- safeUSDC + safeSOL soul-bound tokens
- Gasless relayer infrastructure
Phase 2 — Projects & Bounties (Q4 2025)
- Project workspaces with budget escrow
- Task assignment + bounty locking
- Auto-pay on PR merge
- gitSwap via Jupiter aggregator
- Vault-to-vault transfers
Phase 3 — Scale (Q1 2026)
- CLI (gitsafe) + TypeScript SDK
- Security audit + upgrade authority revocation
- Web dashboard (read-only vault view)
- Multi-repo project support
Phase 4 — DeFi & Ecosystem (Q2 2026)
- Yield on idle vault assets (Jito staking)
- GitSafe DAO + treasury multisig
- $GITSAFE token launch
- GitLab + Bitbucket support
