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

1. Install the CLI

npm install -g goe-cli

2. Global Configuration

Some GoE CLI parameters can be provided either as command-line flags or via environment variables.

Chain ID

Most goe repo commands require a target chain ID. You can specify it in one of the following ways:

• Command-line flag (highest priority):

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

• Environment variable (applies to all commands in the current shell):

export GOE_CHAIN_ID=11155111
goe repo create my-repo

If both are provided, the command-line flag overrides the environment variable.

3. 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.

4. Repo Command

Create and manage on-chain repositories and permissions.

• Create a repository

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

If --chain-id is not provided, GoE will use the GOE_CHAIN_ID environment variable.

• 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>]

5. 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.”