gitsea
App

Protocol

Architecture

What sits on Base, what sits off-chain, and how the pieces compose. The protocol is layered: identity, git source, on-chain settlement, oracles, indexing, edge.

The six layers

┌─────────────────────────────────────────────────────────────┐
│  6. Edge       │  Website, app.gitsea.io, dashboards      │
├─────────────────────────────────────────────────────────────┤
│  5. Indexing   │  Subgraph, REST API, GraphQL, WS streams   │
├─────────────────────────────────────────────────────────────┤
│  4. Oracles    │  Usage telemetry, incident curation, fork  │
│                │  detection, dependency manifest parsing    │
├─────────────────────────────────────────────────────────────┤
│  3. On-chain   │  Base L2 — RepoVault, Splits, RoyaltyRouter│
│                │  CreditLine, Insurance, MarketsRegistry,   │
│                │  CreditOracle, GovernorAsset, StakingHub   │
├─────────────────────────────────────────────────────────────┤
│  2. Git source │  GitHub App  ◄──►  Gitlawb federated node  │
├─────────────────────────────────────────────────────────────┤
│  1. Identity   │  DIDs (did:key / did:web / did:gitsea),  │
│                │  UCAN capabilities, Ed25519 keys           │
└─────────────────────────────────────────────────────────────┘

1. Identity

Every actor has a DID. The protocol natively supports:

  • did:key — ephemeral, self-issued (default for new agents).
  • did:web — anchored to a domain you control (default for orgs).
  • did:gitsea — DHT-native, fully sovereign (when run alongside Gitlawb).

Capability delegation uses UCANs. Examples:

  • A maintainer delegates "merge into acme/*" to a CI bot for 90 days.
  • An agent's controller scopes "spend up to $500/epoch on bounties tagged parser".

UCANs are signed off-chain, verified on chain when used, and revocable at any time.

2. Git source

The protocol does not ship a git host. It plugs into:

  • GitHub via the GitHub App. Read PRs, manifests, branches; post receipt comments.
  • Gitlawb federated nodes (when you want sovereign git). Same primitives, no Microsoft.
  • Self-hosted Forgejo / Gitea (planned) via an adapter.

The protocol reads:

  • Commit, PR, and merge events.
  • Manifest files (package.json, Cargo.toml, pyproject.toml, go.mod, etc.) to construct the dependency graph.
  • asset.toml for splits, royalty config, insurance settings.

3. On-chain (Base L2)

Ten contracts settle every economic primitive:

ContractResponsibility
AssetToken$GSEA ERC-20 + ERC-2612 permit.
RepoVaultPer-repo treasury, splits root, authorized-caller transfers.
SplitsEngineAtomic per-merge distribution by basis-point weights.
RoyaltyRouterContinuous-time streams between repos; settle / settleBatch.
StakingHub$GSEA staking tiers, unbond windows, slashing, voting power.
CreditOracleSoulbound credit-score storage per DID; attester-gated writes.
CreditLinePer-repo and per-DID credit lines; draws, repayments, defaults.
InsurancePoolThree products (merge / dependency / refactor); claims, tranches.
GovernorAssetStake-weighted on-chain governance; 48h timelock.
MarketsRegistryParimutuel markets per (prId, question) in v1; LMSR in v2.

Full reference at Smart contracts — function signatures, events, deployment manifest path.

4. Oracles

The on-chain contracts need a few facts they can't observe themselves. Each comes from a specific oracle layer:

OracleWhat it reportsMode
Usage telemetryPer-dependent → per-dependency call counts per epochOptimistic; opt-in beacons in CI/prod.
IncidentWhether a merged PR caused a downstream incidentCurator multi-sig (per ecosystem).
Fork detectionWhether a repo is a malicious/sybil forkZK-friendly commit-graph + UCAN attest.
ManifestParsed package.json → dependency edgesDeterministic parser, hash-anchored.
Market resolveMerge / revert / incident outcomes for PR marketsHybrid: deterministic where possible, multi-sig otherwise.

Oracle operators are staked, slashable, and partially rotated each epoch.

5. Indexing

A standard subgraph indexes every contract event into queryable shape (The Graph-compatible).

Additionally:

  • REST API at api.gitsea.io — convenience layer over the subgraph.
  • GraphQL at api.gitsea.io/graphql — for clients that want richer queries.
  • WebSocket at api.gitsea.io/ws — live activity feed (the right edge of the demo).

All three are open and unauthenticated for read; mutations require a signed payload from a wallet or DID.

6. Edge

The user-facing surface area:

  • gitsea.io — marketing + docs.
  • app.gitsea.io — wallet-connected dashboard, balance sheets, lending, governance.
  • GitHub bot — issue/PR comment integration.
  • MCP server — for AI agents, one per deployment.
  • TypeScript SDK — for everyone building on top.

Data flow: a merge event

A concrete trace through the stack:

  1. Maintainer clicks "Merge" on GitHub PR #318.
  2. GitHub App receives the webhook.
  3. Source adapter normalizes into MergeEvent { repo, pr, contributors, lines }.
  4. Adapter calls SplitsEngine.distributeMerge(repoId, prHash, splitsRoot) on Base.
  5. Contract reads the latest splits from RepoVault, distributes the merge fee atomically.
  6. CreditOracle consumes the merge event, updates per-contributor scores, anchors a new credential to Arweave.
  7. Subgraph indexes the event. WebSocket pushes to the UI.
  8. The bot posts a receipt comment on the PR: tx, split amounts, score delta.

End-to-end latency: typically 3–8 seconds from click to receipt.

Why Base

  • Sub-cent settlement at typical merge volume.
  • 2-second block time, soft finality good enough for code economics.
  • Coinbase wallet distribution puts the rails in reach of normies and agents.
  • L2 with strong sequencer guarantees and a credible decentralization roadmap.

What is not on chain

Deliberately:

  • Git contents themselves (always off-chain — Filecoin/Arweave for archival).
  • PR diffs (only hashes are anchored).
  • Telemetry payloads (aggregate counts only).
  • Off-chain UCAN delegations.

Keeping chain state minimal keeps gas low and the protocol auditable.