Metadata-Version: 2.1
Name: matrix-contracts
Version: 0.1.0
Summary: Shared protocol buffer definitions and Pydantic schemas for Distributed Matrix Multiplication
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: grpcio>=1.50.0
Requires-Dist: protobuf>=4.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: grpcio-tools>=1.50.0; extra == "dev"

# `matrix-contracts`

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/matrix-compute/matrix-compute-colab/blob/main/01_quickstart_distributed_matmul.ipynb)

Central repository containing interface contracts, Protocol Buffer definitions, and Pydantic validation schemas for the **Distributed Matrix Multiplication** platform.

## Contract Modules

1. **Contract 1: Discovery & Telemetry (`matrix_contracts.schemas.discovery`)**
   - `WorkerAnnouncePayload` (Nostr Kind 30000 event schema with `lightning_routing_pubkey`)
   - `WorkerQueryRequest` / `WorkerQueryResponse`
2. **Contract 2: Direct Compute P2P (`matrix_contracts.v1.pb2` & `pb2_grpc`)**
   - `compute_service.proto`: Defines `MatrixComputeService` gRPC service with `RequestTileTask` (returns `TileTaskAck` readiness) and `ExecuteTileTask` (streaming matrix compute with pre-allocation L402 auth).
3. **Contract 3: Settlement & Fee Split (`matrix_contracts.schemas.settlement`)**
   - `CreateHodlInvoiceRequest` / `CreateHodlInvoiceResponse`
   - `SettlePaymentRequest`
4. **Contract 4: Fraud & Dispute (`matrix_contracts.schemas.fraud`)**
   - `FreivaldsFraudProof`

## Installation

```bash
pip install -e .
```

## Regenerating Protobufs

If `proto/compute_service.proto` is modified, regenerate the Python gRPC stubs:

```bash
python -m grpc_tools.protoc -Iproto --python_out=matrix_contracts/proto --grpc_python_out=matrix_contracts/proto proto/compute_service.proto
```
