{ "markdown": "

\n\n \n \n \n \"The\n\n

\n\n# Open Institutional Custody\n\nAn open-source project by [The Singularity](https://thesingularity.so/).\n\n**Rust components for institutional payment authorization and signing.**\n\nConnect payment approvals and shared spending limits to the exact EVM or Solana\ntransaction each signer verifies. Approvers review the payment independently.\nSigners check the bytes, rules, and receipts before producing signature output.\n\n[Run a transfer](#try-it-locally) · [Follow a payment](docs/payment-flow.md) · [Documentation](docs/README.md) · [Contribute](docs/development.md)\n\n> **Development preview.** Rust libraries and an approval CLI, with real signatures\n> and simulated chains. A complete production deployment is still under development.\n\n## 5-minute quickstart\n\nRun the whole custody flow on your own machine — no accounts, no RPC\ncredentials, no prompts. `oic demo` settles two transfers:\n\n- **EVM** — a development **single-key** secp256k1 signer (1-of-1, *not*\n threshold).\n- **Solana** — a **FROST ed25519 2-of-3** threshold signature.\n\nThen it blocks a theft: an attacker changes the amount in an approved package,\nand the independent verifier refuses to sign it. It ends on the signed audit log.\n\n\n> **Demo recording pending.** The ≤20s `oic demo` GIF is not yet committed —\n> generate it with [`docs/assets/record-demo.sh`](docs/assets/record-demo.sh)\n> (needs `asciinema`+`agg` or `vhs`), then embed `docs/assets/oic-demo.gif` here.\n\n### Zero install — open it in your browser\n\n[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/0xTheSingularity/open-insititutional-custody?quickstart=1)\n\nOne click opens the repo in a GitHub Codespace with Rust 1.95 and the build\ntools ready. The first launch pre-builds the workspace (a few minutes on the\nrecommended 4-core/8 GB machine), then run:\n\n```sh\ncargo run -p oic-cli -- demo\n```\n\nSee [`.devcontainer/README.md`](.devcontainer/README.md) for details.\n\n### 1. Download, verify, then run (recommended)\n\nThe security-minded path: download the installer, read it, let it **verify the\nSHA-256 checksum (and the cosign signature) before it runs anything**, then it\nruns `oic demo`.\n\n```sh\n# Download the installer and read it first\ncurl -fsSLO https://raw.githubusercontent.com/0xTheSingularity/open-insititutional-custody/main/install.sh\n\n# Run it: downloads the oic binary for your platform, verifies the SHA-256\n# (fail-closed on mismatch) and the cosign signature when cosign is installed,\n# then runs `oic demo`.\nsh ./install.sh\n```\n\nVerify the signature yourself, before trusting the binary:\n\n```sh\n# For your platform's tarball (e.g. oic-0.1.3-aarch64-apple-darwin.tar.gz),\n# download the .sha256, .sha256.sig and .sha256.pem from the GitHub release, then:\ncosign verify-blob \\\n --certificate oic-0.1.3-.tar.gz.sha256.pem \\\n --signature oic-0.1.3-.tar.gz.sha256.sig \\\n --certificate-identity 'https://github.com/0xTheSingularity/open-insititutional-custody/.github/workflows/release.yml@refs/tags/v0.1.3' \\\n --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \\\n oic-0.1.3-.tar.gz.sha256\n```\n\nReleases from v0.1.2 also carry a GitHub build provenance ([SLSA](https://slsa.dev))\nattestation for each tarball and the `oic` binary in it. Check one with the GitHub CLI:\n\n```sh\ngh attestation verify oic-0.1.3-.tar.gz \\\n --repo 0xTheSingularity/open-insititutional-custody \\\n --signer-workflow 0xTheSingularity/open-insititutional-custody/.github/workflows/release.yml \\\n --source-ref refs/tags/v0.1.3\n```\n\n### 2. `curl | sh` (convenience fallback)\n\nFaster, but you are piping a remote script into your shell. The installer still\nenforces the SHA-256 check before running:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/0xTheSingularity/open-insititutional-custody/main/install.sh | sh\n```\n\n### 3. `docker run` (any OS, no toolchain)\n\nThe published GHCR image runs `oic demo` as its default command:\n\n```sh\ndocker run --rm ghcr.io/0xthesingularity/open-insititutional-custody:latest\n```\n\nFrom v0.1.2, check the image's build provenance before you run it:\n\n```sh\ngh attestation verify oci://ghcr.io/0xthesingularity/open-insititutional-custody:0.1.3 \\\n --repo 0xTheSingularity/open-insititutional-custody \\\n --signer-workflow 0xTheSingularity/open-insititutional-custody/.github/workflows/release.yml \\\n --source-ref refs/tags/v0.1.3\n```\n\n### 4. Custody in CI\n\nRun the same check in a GitHub Actions workflow, on a Linux or macOS runner:\n\n```yaml\n- uses: 0xTheSingularity/open-insititutional-custody@v0.1.3\n```\n\nThe action installs the matching `oic` release and verifies its checksum, cosign\nsignature, and build provenance. Then it runs `oic demo --check`, which fails the\nstep if the verifier signs the changed package.\n\nThe check tests the `oic` release, not your own code or policy configuration. To\ntest your own build of this repository, set the `binary` input. See\n[Custody check in CI](docs/custody-check.md).\n\n---\n\nPrefer to build from source? Install\n[Git, Rust/Cargo, and platform build tools](docs/getting-started.md#prerequisites),\nthen run the demo straight from the workspace:\n\n```sh\ngit clone https://github.com/0xTheSingularity/open-insititutional-custody.git\ncd open-insititutional-custody\ncargo run -p oic-cli -- demo\n```\n\n[Try Solana 2-of-3 signing](docs/getting-started.md#run-solana-threshold-signing) · [Start the local HTTP stack](docs/local-stack.md) · [Run the full suite](docs/getting-started.md#run-the-full-suite)\n\n## Every decision has a boundary\n\n

\n\n \n \n \n \"Authorize:\n\n

\n\n- **Review independently.** Approvers decode the proposed payment from native transaction bytes.\n- **Reserve shared exposure.** Pending payments count toward the same spending limits.\n- **Verify at the signer.** Each signer checks authorization. A recorded release gates signature output.\n- **Resolve with evidence.** Uncertain payments retain their reservation until chain evidence resolves them.\n\nApproval, signature issuance, and settlement are separate decisions. The default\nD1 authority is a trusted single writer. The experimental D2 profile verifies\nquorum-finalized authority blocks and re-executes them before authorizing signing.\nRead the [payment walkthrough](docs/payment-flow.md) for responsibilities and failure cases.\n\n## What works today\n\n| Area | Implemented | Boundary |\n| --- | --- | --- |\n| **EVM** | Native value and registered ERC-20 transfers | Development single-key ECDSA |\n| **Solana** | SOL and classic SPL transfers with FROST Ed25519 | Simulator-backed signing; no live-chain client |\n| **Signer network** | Roster-admitted Commonware transport, separate signer cores, D1 authority RPC, and fixed-committee D2 Simplex consensus | [Network tests and limits](docs/signer-network.md); no production launcher or committee handoff |\n| **Payment controls** | Independent approvals, policy rules, shared exposure, fee limits, and freezes | Off-chain authorization components |\n| **Operations** | Durable deposits/backfill, reorg reversals, fee/rent journal, reconciliation, and bounded gas-funding/sweeps | Deterministic chain simulators; no live indexer |\n| **Integration** | Vault-scoped HTTP intents, independent grants, crash-safe dispatch, status/evidence, and signed event replay | [Runnable local D1 stack](docs/local-stack.md) with durable simulators; no production launcher |\n| **Recovery and audit** | File-backed state, recorded submissions, signed audit events, and checkpoints | Whole-host rollback needs an independent retained checkpoint |\n\nProduction threshold ECDSA, live-chain clients, arbitrary contract calls, and a complete\ndeployment stack need further implementation. The [protocol v1 contract](spec/protocol-v1.md)\ndocuments the executable RFC002 behavior and remaining production gates. See the\n[capability details](docs/getting-started.md#current-product-boundary) before integrating.\n\nExercise both zero-gas token funding/sweep loops and both HTTP approval flows:\n\n```sh\ncargo test --locked -p oic-service-reconciler --test money_loop\ncargo test --locked -p oic-service-api --test http_flow\n```\n\n## Go deeper\n\n| Start here | What you will find |\n| --- | --- |\n| [Payment walkthrough](docs/payment-flow.md) | One treasury payment, from request to settlement |\n| [Core concepts](docs/concepts.md) | Keys, shares, approvals, exposure, and finality |\n| [Approval client](docs/approval-client.md) | Review and approve payments with `oic-approve` |\n| [Local HTTP stack](docs/local-stack.md) | Bootstrap independent development credentials, send payments, and restart the same stores |\n| [Signer network](docs/signer-network.md) | D1 signing, D2 consensus, embedding contracts, and remaining RFC003 work |\n| [Development](docs/development.md) | Workspace map, focused tests, protocol vectors, and bounded state exploration |\n| [Documentation index](docs/README.md) | Subsystem references and design RFCs |\n\n## Security\n\nThis is a development preview, and we want security researchers to hold the\ncustody protocol to its claims. Every security property is documented with a\n`file:line` citation to the code that enforces it.\n\n- [Threat model](THREAT_MODEL.md) — trust boundaries, assets, and each\n threat mapped to the exact check that stops it, plus known limitations.\n- [Security policy](SECURITY.md) — how to report a vulnerability (private GitHub\n advisories), safe harbor, scope, and the hall of fame.\n\nFound a claim the code does not back up? That is a finding — please report it.\n\n## Contribute\n\nStart with the [development guide](docs/development.md). For setup problems, use\n[troubleshooting](docs/getting-started.md#troubleshooting). For a question or bug,\n[open an issue](https://github.com/0xTheSingularity/open-insititutional-custody/issues)\nwith the commit, command, toolchain, expected result, and error output.\nKeep keys, shares, passphrases, and secret files out of reports.\n\nPackage metadata declares [Apache-2.0](Cargo.toml).\n", "bytes": 11440, "sha": "a134f48fa3cd6f06e3a12be9571f1c45ffa3851979f6d94e8b29aede9c7bf43f", "repo_slug": "0xthesingularity/open-insititutional-custody", "fonte": "repo", "truncated": false, "api": "https://api.agentalog.com/api/listings/okf_0xthesingularity_open_insititutional_cus_b17dc347/readme" }