GoE — Git on Ethereum

GoE is a decentralized Git protocol built on Ethereum and EthStorage, providing a new standard for trustworthy, on-chain code hosting.

It redefines code ownership and verifiability, making your repositories secure, censorship-resistant, and permanently accessible — just like blockchain assets.

With GoE, your code is:

• Censorship-resistant — leveraging Ethereum’s permissionless network and global consensus for truly open collaboration.
• Immutable and traceable — GoE stores Git repository state fully on-chain: smart contracts track branch heads and the metadata of Git objects, while the actual repository data is stored in EthStorage. Together, they provide a tamper-proof, verifiable history.
• Web3-native — fully compatible with Ethereum wallets, DAOs, DApps, and identity systems.
• Fully usable — no new blockchain or extra node infrastructure required.
• Git-native — seamless compatibility with standard Git commands via the goe:// protocol.

---

How GoE Works

GoE uses a three-layer model for seamless Git integration:

1. Git Remote Helper — handles the goe:// protocol for all Git commands.
2. Ethereum Smart Contracts — manage branches, commits, and access permissions on-chain.
3. EthStorage (EIP-4844 Blob) — stores large Git data objects efficiently on Ethereum L2.

📘 Design Document:
For a deeper technical overview of GoE's architecture and on-chain Git mechanics, see our design doc.

---

goe:// Protocol

GoE introduces a custom Git protocol to access on-chain repositories.

goe://<repo_address>:<chain_id>

• <repo_address> — the smart contract address of the repository
• <chain_id> — the chain ID where the repository is deployed

This protocol is automatically handled by the Git Helper installed with goe-cli. No additional setup is required.

---

Getting Started

Install the CLI

npm install -g goe-cli

1. Wallet Command

Manage wallets that act as your on-chain identity.

• Create a wallet

goe wallet create

• List wallets

goe wallet list

• Unlock a wallet

goe wallet unlock

• Lock a wallet

goe wallet lock

🔑 Note: Wallets are secured using a password-derived key stored in your system keychain.

• Unlock: Enter your password to derive a key and store it in the system keychain to decrypt your private key for Git operations.
• Lock: Remove the derived key from the system keychain to secure your wallet.

2. Repo Command

Create and manage on-chain repositories and permissions.

• Create a repository

goe repo create <repo_name> --chain-id <chain_id>

• List repositories

goe repo list --chain-id <chain_id>

• List branches

goe repo branches <repo_address> --chain-id <chain_id>

• Set default branch

goe repo default-branch <repo_address> <branch_name> --chain-id <chain_id>

• Grant / Revoke push access

goe repo grant-push <repo_address> <user_address> --chain-id <chain_id>
goe repo revoke-push <repo_address> <user_address> --chain-id <chain_id>

3. Example Workflow

1). Create or unlock your wallet

goe wallet create
goe wallet unlock

2). Create a new repository on Sepolia

goe repo create my-project --chain-id 11155111

# Output:
# Repo address: 0xABCDEF...

3). Use normal git operations to create the first commit

git init
git remote add origin goe://0xABCDEF...:11155111

echo "# My Project" > README.md
git add .
git commit -m "Initial commit"

4). Push changes on-chain (optionally increase gas)

# The first push creates the branch on-chain (e.g. master),
# and this branch becomes the default branch automatically.
git push origin master

⚠️ Optional: If the push transaction is slow to confirm or becomes stuck, you can temporarily increase the gas price by setting the GOE_GAS_INC_PCT environment variable.

Examples:

• 0 → default gas (no increase)
• 1 → +1% gas
• 100 → +100% gas (double the base gas)

# Increase gas by 10%
GOE_GAS_INC_PCT=10 git push -u origin main

5). Set the default branch

# Only needed if you want to change it later.
goe repo default-branch <repo_address> master --chain-id 11155111

6). Grant collaborator push access

goe repo grant-push <repo_address> <collaborator_address> --chain-id 11155111

Additional Reference

For a practical guide with example commands and workflows, see test-guide.md.

Notes

• GoE is fully compatible with existing Git workflows.

• All commits and repository history are verifiable on-chain.

• “Not your keys, not your code.”