GitShipt documentation

GitShipt turns any GitHub repository into a tradeable Bags.fm token whose lifetime fees flow back to the people who actually build it. A repo owner connects GitHub, picks a payout config, and we mint a token that's tied 1:1 to that repo. As the token trades, fees accumulate; once a day at 00:30 UTC the top contributors receive on-chain SOL transfers proportional to their share of the leaderboard.

Each contributor's score is a weighted sum of GitHub activity over a rolling 30-day window with linear time decay (a contribution today counts in full; a contribution 29 days ago counts at 1/30). The default formula:

score = 3.0 × PRs
      + 1.0 × commits
      + 1.5 × reviews
      + 0.5 × issues
      + 0.2 × log10(1 + netLines)

Bots are excluded automatically. Any login matching /^(.*-bot|dependabot|.*-ci|renovate)$/i is filtered out before ranking. Project owners can override the regex per-project with explicit allow/block lists.

Weights are mutable per-project via scoringConfig.weights; only the top N (default 10) end up in the payout pool.

Two cron-driven workflows run every day:

• 00:00 UTC — snapshot.Recompute every project's leaderboard from the last 30 days of GitHub events. Freeze the result into a snapshot row with a Merkle root.
• 00:30 UTC — payout. For each snapshot, claim accrued Bags fees, then distribute lamports to the top 10 according to the tier weights [0.30, 0.20, 0.15, 0.05 × 7]. Failed sends retry up to 3 times with exponential backoff; persistent failures route to escrow.

Contributors without a linked wallet are paid into a per-contributor escrow row, claimable retroactively the moment they sign in and link a wallet (no funds lost, no expiry).

Earnings are addressed to GitHub usernames at scoring time. To receive them on-chain, contributors:

1. Sign in with GitHub at /auth/signin.
2. Connect a Solana wallet and sign a Sign-In With Solana (SIWS) message. The message includes a per-user nonce, the origin, and a 5-minute expiry.
3. The verified wallet is recorded in contributor_claims and any pending escrow is released on the next payout cycle.

You can link multiple wallets per account but only one is the primary recipient at any given time.

Every project ships an embeddable token card at /embed/r/{org}/{repo}. The route uses a stripped layout (transparent body, no sidebar/footer, robots: noindex), so iframes render only the widget. Default size is 380×360.

<iframe
  src="https://gitshipt.com/embed/r/{org}/{repo}"
  width="380"
  height="360"
  style="border:0;border-radius:12px;color-scheme:light dark"
  loading="lazy"
></iframe>

The Share dropdown in any project header has a one-click “Embed” action that copies this snippet with the current origin pre-filled.

• HMAC-signed webhooks.Every inbound GitHub webhook is verified against the installation's shared secret; mismatches are dropped.
• Sensitive env vars. Treasury keys, GitHub App private keys, and OAuth secrets are scoped to server-only code paths and never reach the browser bundle.
• Append-only audit log. Every administrative action (kill, force-payout, fee change) writes a tamper-evident row with actor, reason, and target.
• Kill switch. A platform-wide halt flag stops every payout in flight and blocks new launches without requiring a redeploy.
• Hot wallet caps. The signing wallet holds only the next ~24 hours of expected payouts; the rest stays in cold custody.