# Contributing to Vaultfire

Welcome. Vaultfire is the canonical accountability + partnership bond protocol, deployed across Base, Polygon, Arbitrum, and Avalanche. This repo is the canonical monorepo, mirrored to **GitLawb** (the original GitHub org was suspended). GitLawb is DID-controlled and decentralized — no platform can take it down.

This guide explains how to contribute as an external developer.

---

## Quick start

```bash
# 1. Clone the canonical repo
git clone gitlawb://did:key:z6MkryiNsYdFEMHv95wxzSQ1vtFXPyVQQrxXdPw3tE5HpfxV/vaultfire
cd vaultfire

# 2. Create a feature branch
git checkout -b your-handle/short-description

# 3. Make your changes, commit
git add .
git commit -m "feat(scope): clear short summary"

# 4. Push and open a PR
git push origin your-handle/short-description
# Then open a PR on https://gitlawb.com/node/repos/z6MkryiN.../vaultfire
```

---

## 1. Identity (DID keypair)

GitLawb uses **DID-based identity** — there are no usernames, passwords, or signups. Every contributor is identified by a cryptographic keypair.

- **Have a DID already?** Use it.
- **No DID?** Generate one with any [did:key](https://w3c-ccg.github.io/did-method-key/) compatible tool (e.g. [`@digitalbazaar/did-method-key`](https://github.com/digitalbazaar/did-method-key), [`did-method-key` CLI](https://github.com/decentralized-identity/did-method-key)).
- Your DID becomes your contributor identity. **Keep the private key secure** — losing it means losing the ability to sign commits under that identity. We will never ask you for it.

> **Trust score:** GitLawb tracks per-DID trust based on signed-push history. New contributors start at zero — that's expected. Trust grows with merged PRs and clean commit history. We review on merit, not trust score.

---

## 2. Forking and cloning

GitLawb supports the standard decentralized git workflow:

```bash
# Clone the canonical repo (read-only for non-maintainers)
git clone gitlawb://did:key:z6MkryiNsYdFEMHv95wxzSQ1vtFXPyVQQrxXdPw3tE5HpfxV/vaultfire
```

If you want your own remote fork, push the cloned repo to a new repository under your own DID:

```bash
git remote add fork gitlawb://did:key:<YOUR-DID>/vaultfire
git push fork main
```

> **Note:** GitLawb is alpha (`v0.1.0-alpha`). The fork-button UX is not yet polished, but the underlying primitive (clone + push to a repo you own) works. If you hit a snag, open an issue.

---

## 3. Branch naming

Use the format `<your-handle>/<short-description>`. Examples:

- `alice/fix-bond-distribution-rounding`
- `bob/docs-x402-endpoint-typo`
- `carol/feat-arbitrum-deployment-script`

For agent contributors (yes, agents can contribute too — Vaultfire is built for that), use your agent DID's short identifier as the handle.

---

## 4. Commit messages

We follow [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>(<scope>): <short summary>

<optional longer body explaining the WHY, not the WHAT>

<optional footers, e.g. "Fixes #123" or "Co-authored-by: did:key:...">
```

**Types:** `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `ci`, `audit`

**Scopes (Vaultfire-specific):**
- `accountability` — AIAccountabilityBondsV2 changes
- `partnership` — AIPartnershipBondsV2 changes
- `escrow` — escrow contract changes
- `x402` — paid endpoint / agentic.market integration
- `helixa` — Helixa trust integration
- `agentkit`, `langchain`, `mcp` — external integrations
- `docs`, `tests`, `scripts`, `deploy`

**Examples:**
- `feat(partnership): add quality-multiplier guardrail for >5yr bonds`
- `fix(x402): correct USDC decimals in trust/street-cred endpoint`
- `docs(accountability): clarify flourishing-score formula in README`

---

## 5. Code style

### Solidity (smart contracts)

- Solidity `^0.8.20` (matches deployed V2 contracts)
- Run `forge fmt` before committing
- Run `forge test -vv` and ensure all tests pass
- **NEVER** modify a deployed contract address in source — that would break the on-chain record
- Storage layout changes require a new contract version (V3, V4) — never modify V2 storage

### TypeScript / JavaScript

- Node `>=20`, ESM modules
- Run `npm run lint` and `npm run format` before committing
- Run `npm test` and ensure all tests pass
- Use `tsx` for executable scripts

### Python

- Python `>=3.11`
- Format with `ruff format`
- Lint with `ruff check`
- Type-check with `pyright` where types are used

---

## 6. Pull request flow

1. **Open a PR** from your branch against `main`
2. **Title:** match conventional commit format (`feat(scope): short summary`)
3. **Description:**
   - What changed and why (link any related issue)
   - How it was tested (commands run, output snippets)
   - Any breaking changes (call them out explicitly)
   - Screenshots / output for UX or chain changes
4. **CI:** wait for CI to pass (tests, lint, contract verification)
5. **Review:** a maintainer will review. We aim to respond within 72 hours.
6. **Merge:** maintainer merges with squash; you keep authorship attribution via your signed DID.

### What gets PRs merged fast

- Clear scope (one concern per PR)
- Tests included
- README/docs updated if behavior changed
- Conventional commit + clean diff
- Replies to review comments are timely and direct

### What gets PRs rejected

- Touching deployed contract addresses
- Removing existing tests instead of fixing them
- Adding new dependencies without justification in the PR description
- Submitting secrets (private keys, mnemonics, API tokens) — **never commit secrets**. If you ever push one by accident, rotate it immediately and tell a maintainer.

---

## 7. Issues

GitLawb tracks issues as git refs (decentralized — every peer mirrors them). Open issues at the repo's `issues` tab.

**For bug reports**, include:
- What you expected
- What happened
- Steps to reproduce (commands, chain, contract address, tx hash if applicable)
- Your environment (OS, Node version, Solidity/Forge version)

**For feature requests**, include:
- The problem you're trying to solve (not the solution)
- Why it matters
- Any context on prior approaches

**For security issues**, **DO NOT open a public issue.** See §9 below.

---

## 8. Code of conduct

- Be technical, not personal
- No slurs, harassment, or demeaning language
- Disagreements get resolved on technical merit
- Maintainers reserve the right to remove disruptive contributors and revoke their signed-push privileges on this repo's mirror

---

## 9. Security

Vaultfire holds real value on-chain. Treat all security findings seriously.

- **Do NOT open a public issue** for vulnerabilities
- Email the maintainer with `[SECURITY]` in the subject (contact in repo metadata)
- Or DM `@ghostkey316` on X with a heads-up that you have a security report ready to share over an encrypted channel
- We'll acknowledge within 48 hours and coordinate disclosure

**Scope:**
- AIAccountabilityBondsV2 (`0x6750D28865434344e04e1D0a6044394b726C3dfE` on Base)
- AIPartnershipBondsV2 (`0x01C479F0c039fEC40c0Cf1c5C921bab457d57441` on Base)
- Vaultfire Escrow contract
- x402 endpoint handlers on `theloopbreaker.com`
- Helixa trust integration

**Out of scope:**
- Issues in unverified third-party clones
- Social engineering of maintainers
- DoS via spamming GitLawb's own infrastructure (report to GitLawb directly)

---

## 10. License

MIT. By contributing, you agree your contributions are licensed under MIT.

---

## Getting help

- **Repo:** https://gitlawb.com/node/repos/z6MkryiNsYdFEMHv95wxzSQ1vtFXPyVQQrxXdPw3tE5HpfxV/vaultfire
- **X:** [@ghostkey316](https://x.com/ghostkey316)
- **Site:** https://theloopbreaker.com
- **Live demos:** https://theloopbreaker.com/helixa

Welcome to Vaultfire. Build something real.
