Metadata-Version: 2.4
Name: umarise
Version: 1.0.0
Summary: Anchor files to Bitcoin. Verify proofs offline. Content-blind proof-of-existence infrastructure.
Project-URL: Homepage, https://umarise.com
Project-URL: Documentation, https://umarise.com/developers
Project-URL: Repository, https://github.com/AnchoringTrust/umarise-python
Project-URL: API Reference, https://umarise.com/api-reference
Project-URL: Anchoring Specification, https://anchoring-spec.org
Project-URL: Independent Verification, https://verify-anchoring.org
Author-email: Umarise <support@umarise.com>
License: MIT
License-File: LICENSE
Keywords: ai-governance,anchoring,audit,bitcoin,compliance,evidence,hash,integrity,opentimestamps,proof-of-existence,timestamp,verification
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# umarise

**Anchor files to Bitcoin. Verify proofs offline.**

Content-blind proof-of-existence infrastructure. Umarise never receives your file, only its SHA-256 hash.

[![PyPI](https://img.shields.io/pypi/v/umarise)](https://pypi.org/project/umarise/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

## Install

```bash
pip install umarise
```

## Quick start (CLI)

```bash
# 1. Get your free API key at https://umarise.com/developers
export UMARISE_API_KEY=um_your_key_here

# 2. Anchor a file
umarise anchor contract.pdf

# 3. After ~2 hours (Bitcoin confirmation), get full proof
umarise proof contract.pdf

# 4. Verify — no API key needed, works offline
umarise verify contract.pdf
```

### Expected output

```
$ umarise anchor contract.pdf
✓ hash computed: sha256:a1b2c3d4e5f6...
✓ anchored: origin_id f47ac10b-58cc-4372-a567-0e02b2c3d479
ℹ proof.ots pending — Bitcoin confirmation takes ~2 hours
✓ certificate saved: contract.pdf.proof
✓ receipt: contract.pdf.certificate.json

$ umarise proof contract.pdf        # after ~2 hours
✓ hash: sha256:a1b2c3d4e5f6... (already anchored)
✓ origin_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
✓ anchored in Bitcoin block 943943
✓ no later than: 2026-04-06
✓ saved: contract.pdf.proof
✓ extracted: contract.pdf-proof/
✓ proof valid — independent of Umarise

$ umarise verify contract.pdf
✓ hash matches
✓ anchored in Bitcoin block 943943
✓ no later than: 2026-04-06
✓ proof valid — independent of Umarise
```

## Python SDK

```python
from umarise import UmariseClient

client = UmariseClient(api_key="um_your_key_here")

# Anchor a file (hash computed locally, file never leaves your machine)
result = client.anchor("contract.pdf")
print(result.origin_id)   # f47ac10b-...
print(result.hash)         # sha256:a1b2c3...

# Check proof status
proof = client.proof(result.origin_id)
if proof.status == "anchored":
    print(f"Bitcoin block: {proof.bitcoin_block_height}")

# Anchor a pre-computed hash (for pipelines)
result = client.anchor_hash("sha256:a1b2c3d4e5f6...")

# Resolve metadata (no API key required)
origin = client.resolve(origin_id="f47ac10b-...")
origin = client.resolve(hash="sha256:a1b2c3...")

# Verify a hash (no API key required)
check = client.verify("sha256:a1b2c3d4e5f6...")
if check["found"]:
    print(check["origin"])
```

## How it works

1. **Hash locally** — SHA-256 is computed on your machine. Your file never leaves.
2. **Anchor** — The hash is submitted to the Umarise registry and queued for Bitcoin anchoring.
3. **Bitcoin confirms** — Within ~2 hours, the hash is embedded in a Bitcoin block via OpenTimestamps.
4. **Verify independently** — Anyone with the file and `.proof` bundle can verify. No API, no account, no Umarise dependency.

## The .proof bundle

```
contract.pdf.proof (ZIP)
├── certificate.json    # origin metadata (hash, origin_id, timestamp, block)
├── proof.ots           # binary OpenTimestamps proof (Bitcoin anchor)
├── artifact.pdf        # copy of the original file (proof command only)
└── VERIFY.txt          # verification instructions
```

> **Important:** The `.proof` file must be in the same directory as the original file for `verify` to find it automatically.

## CI/CD

For automated anchoring in GitHub Actions, use the official action:

```yaml
- uses: AnchoringTrust/anchor-action@v1
  with:
    api-key: ${{ secrets.UMARISE_API_KEY }}
    files: dist/build.tar.gz
```

→ [GitHub Marketplace: Umarise Anchor](https://github.com/marketplace/actions/umarise-anchor)

## Pricing

Your API key includes **100 free anchors**. No email, no account required.

For production use, see [umarise.com/pricing](https://umarise.com/pricing).

## Links

- [Documentation](https://umarise.com/developers)
- [API Reference](https://umarise.com/api-reference)
- [Anchoring Specification](https://anchoring-spec.org)
- [Independent Verification](https://verify-anchoring.org)
- [npm CLI](https://www.npmjs.com/package/@umarise/cli) (Node.js alternative)
- [Status](https://umarise.com/status)

## License

MIT
