commitments

KO | EN

gitlite — search

#cpp #shell #cloud-native #nextjs #graphql #vue #claude #framework #gemini #golang

(★ 9)

A prototype for self-enforcing stake-backed promises.

파일 탐색기

ZIP 다운로드

- - ci.yml
  - verification.yml
- - privacy.md
- - README.md
- - ERC-COMMITMENTS-AGREEMENTS.md
  - ERC-COMMITMENTS-MESH.md
  - ERC-COMMITMENTS-MUTUALS.md
  - ERC-COMMITMENTS-REWARDS.md
  - ERC-COMMITMENTS-SERVICES.md
  - ERC-COMMITMENTS.md
  - manifest.json
  - README.md
- README.md
- - favicon.svg
- - audit-legacy.mjs
  - docs-probe.mjs
  - qa-probe.mjs
  - screenshot-vault.mjs
- - generated.ts
  - index.css
  - main.tsx
  - router.tsx
- .env.example
- .gitignore
- .stylelintrc.json
- eslint.config.js
- index.html
- package.json
- README.md
- tsconfig.app.json
- tsconfig.json
- tsconfig.node.json
- vite.config.ts
- vitest.config.ts
- vitest.setup.ts
- wagmi.config.ts
- - deployments.v1.example.json
- - abiBindings.test.ts
  - abis.ts
  - accountStats.ts
  - agent-abis.ts
  - agents.ts
  - arbitrationMechanisms.ts
  - env.ts
  - governance-abis.ts
  - governance.ts
  - index.ts
  - integration.test.ts
  - ledgerFlow.ts
  - loadDeployments.test.ts
  - loadDeployments.ts
  - metadataFetcher.test.ts
  - metadataFetcher.ts
  - mutual.ts
  - vaultCover.ts
- .env.example
- offchain.schema.ts
- package.json
- ponder.config.ts
- ponder.schema.ts
- README.md
- tsconfig.json
- tsconfig.tsbuildinfo
- forge-std
- openzeppelin-contracts
- openzeppelin-contracts-upgradeable
- - catalogue.mjs
- check-docs.mjs
- check-guide-vocab.mjs
- check-unit-constants.mjs
- compat-snapshot.mjs
- compat-topology.json
- DeployAdaptersAndStrategies.s.sol
- DeployCommitmentManager.s.sol
- DeployGovernance.s.sol
- DeployMesh.s.sol
- DeployMutual.s.sol
- DeployOperatorRegistry.s.sol
- DeployOperatorServiceRegistry.s.sol
- DeployRewardsCoordinator.s.sol
- DeploySepolia.s.sol
- DeployVaultFactory.s.sol
- forge-doc-flatten.mjs
- foundry-artifacts.mjs
- foundry-artifacts.test.mjs
- gen-selectors.mjs
- pin-metadata.mjs
- Simulate.s.sol
- write-frontend-env.mjs
- dump-governance-abis.mjs
- - ERC20StaticAdapter.sol
  - ERC4626Adapter.sol
- - CounterpartyPremiumStream.sol
  - FlatFeeAtCreate.sol
  - IndexAppreciationYield.sol
- - Constants.sol
- README.md
- - Adapters.t.sol
- - ERC8004IdentityRegistry.t.sol
- - ArbiterCapabilities.t.sol
  - AttestationArbiter.t.sol
  - ManualArbiter.t.sol
  - OptimisticInsuranceArbiter.t.sol
  - TwoTierArbiter.t.sol
- - RewardsCoordinatorInvariants.t.sol
- - CommitmentsGovernor.Forfeit.t.sol
  - CommitmentsGovernor.t.sol
  - CommitmentsGovernor.WeightUpdate.t.sol
  - GovernorFactory.t.sol
  - GovernorTestBase.sol
  - TokenWeightingTransferGovernance.t.sol
  - TokenWeightingVotesShim.t.sol
- - EnvelopeSig.sol
  - ManagerTestBase.sol
  - MockConsumer.sol
  - MockERC20.sol
  - MockERC20Permit.sol
  - MockStrategy.sol
  - SkimmingMockStrategy.sol
- - Agreement.t.sol
  - CreateAndFund.t.sol
  - Custody.t.sol
  - HookLiveness.t.sol
  - Lifecycle.t.sol
  - MovementValidation.t.sol
  - Mutual.t.sol
  - StorageSlots.t.sol
- - FanInNode.t.sol
  - FanOutAllocationCaps.t.sol
  - FanOutNode.t.sol
  - FlowPathLib.t.sol
  - GasBenchmark.t.sol
  - Integration.t.sol
  - MeshBackingInvariant.t.sol
  - MeshFactory.t.sol
  - MeshFactoryPolicy.t.sol
  - TokenWeighting.t.sol
  - TokenWeightingRetirement.t.sol
  - TokenWeightingWeightEpoch.t.sol
- - Mutual.t.sol
  - PremiumPolicy.t.sol
- - OperatorCommission.t.sol
  - OperatorRegistry.t.sol
  - OperatorRegistryAcceptance.t.sol
  - OperatorRegistryMetadata.t.sol
  - OperatorRegistryMulticall.t.sol
  - OperatorRegistrySig.t.sol
  - OperatorRegistryStakeAt.t.sol
- - CommitmentsRewardsCoordinator.t.sol
  - MerkleHelper.sol
  - MerkleSnapshot.t.sol
  - MerkleSnapshotAdapter.t.sol
  - MockServiceManager.sol
  - RewardsCoordinatorFactory.t.sol
  - RewardsCoordinatorIntegration.t.sol
- - OperatorServiceRegistry.t.sol
- - CounterpartyPremiumStream.t.sol
  - FlatFeeAtCreate.t.sol
  - IndexAppreciationYield.t.sol
- - CommitmentsVault.t.sol
  - CommitmentsVaultDonate.t.sol
  - CommitmentsVaultMetadata.t.sol
  - ForfeitDonationBeneficiary.t.sol
  - IdleStrategy.t.sol
  - InflationAttack.t.sol
  - PremiumSkimStrategy.t.sol
  - VaultCoverConduit.t.sol
  - VaultFactory.t.sol
  - VaultFactoryPolicy.t.sol
- StorageSlots.t.sol
- - certora-local.sh
  - fv-toolchain-rebuild.sh
- - CreateCommitmentSmoke.t.sol
  - CreatePathsSmoke.t.sol
  - Eip712Envelope.t.sol
  - EscrowIsolationSmoke.t.sol
  - ForfeitBoundarySmoke.t.sol
  - HalmosBase.sol
  - MerkleClaimReplay.t.sol
  - MeshTermination.t.sol
  - MovementCapSmoke.t.sol
  - MutualMathSmoke.t.sol
  - RegistryDelegation.t.sol
- - AdversarialStrategies.sol
  - medusa.json
  - MedusaManagerHarness.sol
- MUTATION-RESULTS.md
- PROPERTIES-ERC-MAP.md
- PROPERTIES.md
- README.md
.editorconfig
.gitignore
.gitmodules
.npmrc
CLAUDE.md
COMMITMENTS.md
docker-compose.yml
foundry.lock
foundry.toml
GOAL.md
halmos.toml
justfile
LICENSE
NEXT_STEPS.md
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
remappings.txt

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A **commitment** is a stake-backed promise: capital locked behind an obligation, which a chosen arbiter can seize if the promise is broken.

Mechanically, each commitment is a **parameterized lien**: it names an arbiter empowered to forfeit, an optional counterparty, penalty bounds, and an unbonding period, and enforcement runs through a two-phase forfeit with a minimum one-day challenge window, so no one loses their stake in a single block. Because the lien is a standard primitive, it composes: two liens facing each other form a bilateral **agreement**, pooled liens form **mutual coverage** (several-liability insurance with streamed premiums), and a **mesh topology** aggregates committed stake into governance- and service-compatible voting power. Rewards, on-chain governance, and [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) agent identity for AI-agent bonds build on the same substrate: one primitive, scaling from a handshake between two parties to an insurance market.

Commitments makes an economic promise legible as a bounded lien on productive capital. A participant keeps a clearly attributable position while accepting explicit rules for release, forfeiture, distribution, or shared loss.

The design favors composition over a universal market contract:

- Core provides direct custody, commitment lifecycle, and validated token movements.
- Agreements and Mutuals add bilateral and pooled coordination without creating a second custody root.
- Mesh and Services translate committed positions into application-specific stake and signing policy.
- Rewards distributes service-funded value independently through cumulative Merkle roots.
- Optional vaults, arbiters, governance, and agent identity components remain outside conformance-critical Core.

## How it works

1. **Fund** — a user deposits tokens into the CommitmentManager, which tracks a per-(token, user) *free / encumbered* ledger.
2. **Commit** — the user creates a commitment: an amount of backing, an arbiter, an optional counterparty, penalty bounds, and an unbonding period. The backing is encumbered but never leaves productive use — a **backing adapter** prices it (`indexNow`, payout denomination) whether it's a plain ERC-20 or an appreciating 4626 share.
3. **Enforce** — if the promise is broken, the arbiter initiates a forfeit. A challenge window (minimum 1 day) allows dispute; after it elapses the forfeit executes and the payout is claimable pull-payment style.
4. **Release** — commitments that run their course release cleanly, returning the backing to the free balance after unbonding.
5. **Distribute** — strategies bound to commitments move value (yield share, flat fees, premium streams, operator commissions) through a validated, invariant-checked movement pipeline.

## Key concepts

- **Commitment** — a stake-backed promise, implemented as a parameterized lien on manager-custodied backing: amount, arbiter, optional counterparty, penalty bounds, unbonding period
- **Agreement** — a bilateral commitment with symmetric enforcement; both sides lock stake and either can trigger a forfeit
- **Backing adapter** — stateless pricer that lets any ERC-20 or appreciating ERC-4626 share serve as commitment backing
- **Distribution strategy** — pluggable contract that moves value (yield, fees, premiums) via a validated movement pipeline, bounded by the commitment it's bound to
- **Two-phase forfeit** — initiate, then a challenge window (minimum one day) before execution; payouts are pull-payment
- **Partition invariant** — `Σ(free + encumbered) + Σescrow == balanceOf(manager)` per token, fuzz-locked in the conformance suite
- **Magnitude allocation** — `totalForfeitable ≤ totalEncumbered` per (user, token); prevents over-commitment
- **Mesh topology** — composable FanIn/FanOut/Weighting graph for stake aggregation and governance integration
- **Mutual coverage** — groups share losses several-liability via a loss index Λ while premiums stream to underwriters

## Documentation

- [Documentation overview](docs/README.md) — authority policy and current entry points
- [Standards family](docs/standards/README.md) — core Commitments plus Agreements, Mesh, Mutuals, Rewards, and Services
- [Architecture overview](docs/protocol/architecture/overview.md) — five-layer stack, dependency graph, proxy patterns
- [Contract interactions](docs/protocol/architecture/contract-interactions.md) — sequence diagrams for key flows
- [Storage layout](docs/protocol/architecture/storage-layout.md) — EIP-7201 namespaced storage slots
- [Security model](docs/protocol/security/security-model.md) — threat model and trust assumptions
- [Deployment guide](docs/protocol/operations/deployment.md) — configuration and deployment
- [Use cases](docs/protocol/use-cases/) — agent bonds, NAV-floor insurance, attestation-based insurance, mutual aid, cross-vault underwriting, two-party tranches

The shipped Solidity contracts define current behavior and ABI. Standards formalize that implementation; generated references describe it mechanically; guides explain how to use it. Contract reference pages are generated from NatSpec via `just docs-gen`, and the frontend serves current material under its built-in `/app/docs/*` viewer.

### Role guides

| Role | Guide |
|------|-------|
| Depositor | [guides/depositor.md](docs/protocol/guides/depositor.md) |
| Operator | [guides/operator.md](docs/protocol/guides/operator.md) |
| Arbiter | [guides/arbiter.md](docs/protocol/guides/arbiter.md) |
| Two-tier court deployer | [guides/two-tier-arbiter.md](docs/protocol/guides/two-tier-arbiter.md) |
| Integrator | [guides/integrator.md](docs/protocol/guides/integrator.md) |
| Mutual member | [guides/mutual.md](docs/protocol/guides/mutual.md) |
| Service wiring | [guides/service-wiring.md](docs/protocol/guides/service-wiring.md) |

## Getting started

### Prerequisites

- [Foundry](https://book.getfoundry.sh/) (forge, cast, anvil)
- [just](https://github.com/casey/just), [pnpm](https://pnpm.io/) and Node 20+ for the frontend/indexer workspace
- Docker (**optional**) — only for the local IPFS node that gives seeded commitments their full metadata. Everything works without it; see below for exactly what changes.

### Build & test

```bash
git clone --recurse-submodules https://github.com/AInima-Collective/commitments.git
cd commitments
just build     # forge build
just test      # forge test
```

Foundry dependencies are committed as pinned git submodules, with revisions
recorded in `foundry.lock`. For an existing clone, restore the exact dependency
set with `git submodule update --init --recursive`; no floating `forge install`
step is required.

The suite is 1,000+ Foundry tests covering the manager ledger and commitment lifecycle, forfeit mechanics (including stale-proposal force-cancel), agreements, adapters and strategies, vault operations, mesh topology, services, mutual coverage, rewards, governance, gas benchmarks, and EIP-7201 storage-layout locks. A dedicated conformance suite (`test/manager/conformance/`) fuzzes the core ERC-Commitments invariants.

### Local development (anvil + indexer + frontend)

One command boots the whole stack — starts anvil in the background, deploys every contract, seeds depositors / operators / commitments / agreements / mutuals, and writes the fresh addresses into `frontend/.env.local`:

```bash
pnpm install       # installs the frontend + indexer workspace (run from repo root)
just ipfs-up       # optional, see below — start it BEFORE dev-up
just dev-up        # anvil + deploy + seed + env sync
just indexer-dev   # Terminal 2: Ponder indexer on :65422 (powers graph views)
just frontend-dev  # Terminal 3: Vite dev server on :5173
just dev-down      # stop the background anvil when done
```

Connect a wallet to `http://127.0.0.1:8545` (chain ID 31337) and import anvil's default private key (`0xac0974...ff80`) to interact with the seeded protocol. The indexer discovers contract addresses by parsing `broadcast/**/run-latest.json`, so it needs no manual configuration.

#### Commitment metadata, and why `just ipfs-up` is worth one command

Seeded commitments carry off-chain `commitment.v1` metadata — a title, a
description, tags, and a link to a full terms document — so the app shows what
each commitment is *about* rather than a bare `#12`. How much of that survives
depends on where the payload can be stored, because `metadataURI` is capped at
**512 bytes on chain**:

| | URI | what you get |
|---|---|---|
| **with `just ipfs-up`** | `ipfs://…` — 66 bytes at any size | full descriptions, plus a terms document per commitment that actually resolves |
| **without** | `data:application/json;base64,…` — carries the whole payload | one-sentence descriptions, no terms links |

An inline `data:` URI has to fit the entire document inside 512 bytes, which is
about 360 bytes of JSON — roughly one sentence once a terms link is present. An
`ipfs://` URI is 66 bytes no matter how long the document is.

Nothing else differs, and **no step requires Docker**: `just dev-up`, the
indexer, and the frontend all work with the daemon stopped. The pieces
auto-detect a node on the conventional ports, so there is nothing to export:

```bash
just ipfs-up   # Kubo via docker compose: API on :5001, gateway on :8080
just dev-up    # detects it, pins the full payloads, writes VITE_IPFS_GATEWAY
```

Set `IPFS_API_URL=none` to force the inline path even with a daemon running
(that is how the no-Docker path gets tested). If a node is up but pinning fails
or times out, the seed logs it and falls back to the inline payloads rather than
aborting — an IPFS problem should never block a deploy.

Payload text lives in `script/metadata/catalogue.mjs`, one entry per seeded
commitment with a `full` and a `short` variant. `script/pin-metadata.mjs` runs
before the seed (it is the first line of `just anvil-seed`) and writes
`script/metadata-manifest.json`, which `Simulate.s.sol` reads back — the seed is
Solidity and cannot POST to IPFS, and `metadataURI` is immutable once written,
so the pinning has to happen first.

### Deploy

Deployment scripts live in `script/` — one per subsystem (`DeployCommitmentManager`, `DeployVaultFactory`, `DeployAdaptersAndStrategies`, `DeployOperatorRegistry`, `DeployOperatorServiceRegistry`, `DeployMesh`, `DeployMutual`, `DeployRewardsCoordinator`, `DeployGovernance`), plus `DeploySepolia.s.sol` for a full testnet stack and `Simulate.s.sol` for the seeded local deployment. See the [deployment guide](docs/protocol/operations/deployment.md) for ordering, configuration, and environment variables.

## Formal verification

`verification/` holds a three-tool stack — Certora CVL specs, Halmos bounded symbolic execution, and Medusa coverage-guided fuzzing — with the property inventory in [`verification/PROPERTIES.md`](verification/PROPERTIES.md):

```bash
just fv-halmos            # symbolic execution of verification/halmos/ harnesses
just fv-certora-check     # compile + typecheck the CVL specs locally
just fv-medusa 3600       # hour-long coverage-guided fuzz campaign
```

## Standards

| Standard | Usage |
|----------|-------|
| [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) | Yield-bearing vaults; canonical commitment backing via the ERC4626Adapter |
| [EIP-7201](https://eips.ethereum.org/EIPS/eip-7201) | Namespaced storage on every long-lived contract (slot layouts locked by tests) |
| [EIP-1153](https://eips.ethereum.org/EIPS/eip-1153) | Transient-storage reentrancy guard on all state-mutating entry points |
| [ERC-1967](https://eips.ethereum.org/EIPS/eip-1967) / UUPS | Upgradeable singletons (manager, registries) and per-asset vault proxies |
| [EIP-1167](https://eips.ethereum.org/EIPS/eip-1167) | Minimal proxy clones for mesh node deployment |
| [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) | Agent identity registry for AI-agent bonds |

## Repository structure

```
src/
  core/            Manager custody root, aggregate interfaces, lifecycle libraries
  backing/         Backing adapters (ERC20Static, ERC4626)
  distributions/   Distribution strategies (yield, fees, and premiums)
  extensions/      Agreements, mutuals, mesh, services, and rewards families
  periphery/       Agents, arbiters, governance, and vault products
  shared/          Arbitration, factories, interfaces, registries, utilities
  vendor/          Byte-preserved third-party Solidity (ERC-8004 registry)
test/              Foundry tests mirroring src/ + manager/conformance/ invariant suite
verification/      Certora + Halmos + Medusa formal verification stack
script/            Deploy scripts + Simulate.s.sol (full-stack anvil seeder)
docs/              Standards, current protocol docs, and design drafts
frontend/          React + Vite + wagmi dapp (pnpm workspace)
indexer/           Ponder indexer with GraphQL + REST endpoints
```

## Prior work and gratitude

This protocol builds on ideas from earlier restaking and shared-security work in the Cosmos ecosystem:

- [Mesh Security](https://github.com/osmosis-labs/mesh-security) — cross-chain shared security where chains mutually stake to secure each other, proposed by Sunny Aggarwal at Cosmoverse 2022 and implemented in CosmWasm by [Ethan Frey](https://github.com/ethanfrey) and the Confio team. The mesh topology layer here (fan-in/fan-out nodes aggregating stake into voting power) descends from that model.
- [cw-commitments](https://github.com/Lay3rLabs/cw-commitments) — a CosmWasm smart contract implementation of restaking by Layer, whose commitment vocabulary and custody model partially inspired this protocol.

Special thanks to [Spencer Graham](https://github.com/spengrah) for crucial feedback on the design of the protocol.

## License

[MIT](LICENSE)

commitments

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README