Quickstart#

Install the consumer SDK (Python ≥ 3.10). The import name is matrix_compute.

pip install matrix-compute-sdk

The SDK connects to the public production relay (wss://relay.matrix-compute.net) and settlement service (https://settlement.matrix-compute.net) automatically — no environment variables required:

import numpy as np
from matrix_compute import distributed_matmul

A = np.random.randn(8192, 8192).astype(np.float32)
B = np.random.randn(8192, 8192).astype(np.float32)

C = distributed_matmul(A, B, dtype="fp32", partitioning_strategy="output_grid_2d")

For local development or private relays, override the endpoints via environment variables or ClientConfig:

# Optional: override defaults for local development
export MATRIX_NOSTR_RELAYS=ws://127.0.0.1:8008
export MATRIX_SETTLEMENT_API_URL=http://127.0.0.1:8080

from matrix_compute import MatrixComputeClient

with MatrixComputeClient(mode="trial") as client:
    C = client.matmul(A[:4096, :4096], B[:4096, :4096])
    assert np.allclose(C, A[:4096, :4096] @ B[:4096, :4096], atol=1e-3)

Prefer zero install? Launch the interactive Google Colab notebooks directly in your browser:

• 01 — Quickstart: Distributed Matrix Multiplication & Zero-Drain Trial Sandbox
• 02 — Partitioning Strategies Benchmark (3D vs. 1D Outer Product vs. 2D Output Grid)
• 03 — Confidential Computing (TEE) Attestation & AES-256-GCM Demo

Architecture#

Four components cooperate; only the consumer SDK runs on your machine.

Flow: discover (Kind 30000) → escrow (HODL invoice held) → dispatch (gRPC MatrixComputeService) → verify (Freivalds) → settle or dispute (fraud proof slashes the bond, invoice is cancelled).

MatrixComputeClient#

High-level client that owns discovery, escrow, the gRPC channel pool and the orchestrator. Thread-safe and usable as a context manager.

MatrixComputeClient(config: ClientConfig | None = None, **kwargs)

If config is omitted, settings resolve as explicit kwargs → MATRIX_* environment variables → defaults. Any ClientConfig field can be passed as a kwarg.

client.matmul(A, B, ...)

client.matmul(
    A: np.ndarray,                     # (M, K)
    B: np.ndarray,                     # (K, N)
    dtype: str | None = None,          # "fp32" | "fp16" | "bf16"
    tile_size: int | None = None,      # default: config.default_tile_size (1024)
    partitioning_strategy: str | PartitioningStrategy | None = None,
    num_strips: int | None = None,     # OUTER_PRODUCT_1D
    grid_rows: int | None = None,      # OUTPUT_GRID_2D  P_r
    grid_cols: int | None = None,      # OUTPUT_GRID_2D  P_c
    grid_shape: tuple[int, int] | None = None,
) -> np.ndarray                       # (M, N)

Raises MatrixDimensionError for non-2D, empty or mismatched inputs, and MatrixComputeError subclasses for dispatch, verification or payment failures.

client.power_iteration(A, ...)

client.power_iteration(
    A: np.ndarray,
    v0: np.ndarray | None = None,
    iterations: int = 100,
    dtype: str | None = None,
    lease_ttl_seconds: int | None = None,      # remote VRAM lease (default 3600)
    spot_check_probability: float | None = None,  # Freivalds sampling per step (default 0.05)
    normalize: bool = False,
) -> np.ndarray

Computes Aᵏ v₀ with stateful VRAM session leasing: A is uploaded once and stays resident on the worker; only vectors move per step.

client.close()

Releases channels, thread pools and mock workers. Idempotent; called automatically by with.

Top-level functions#

from matrix_compute import distributed_matmul, distributed_power_iteration

C = distributed_matmul(A, B, dtype="fp32", config=None, tile_size=None,
                       partitioning_strategy=None)
v = distributed_power_iteration(A, v0=None, iterations=100, dtype="fp32",
                                config=None, lease_ttl_seconds=None)

One-shot wrappers that create and close a MatrixComputeClient for you. A matrix-compute CLI entry point is also installed.

ClientConfig#

Pydantic model; every field can be set via kwargs or the listed environment variable.

from matrix_compute import ClientConfig, MatrixComputeClient

config = ClientConfig(
    min_worker_vram_mb=16384,
    max_price_per_gflop=0.0008,
    max_budget_sats=50_000,
    freivalds_rounds=8,
)
client = MatrixComputeClient(config=config)

Partitioning strategies#

For C (M×N) = A (M×K) · B (K×N), the strategy decides what each worker receives and therefore how many bytes cross the WAN. Total work is always 2·M·K·N FLOPs. Counts below are in matrix elements; R_down is download redundancy (downloaded / (M·N) − 1).

from matrix_compute import PartitioningStrategy

# 4 x 8 output grid across 32 workers
C = client.matmul(A, B, partitioning_strategy=PartitioningStrategy.OUTPUT_GRID_2D,
                  grid_shape=(4, 8))

# 16 K-strips
C = client.matmul(A, B, partitioning_strategy="outer_product_1d", num_strips=16)

Use the MCP estimate_job_cost tool (backed by the SDK's BandwidthProfiler) to get exact MB and sat estimates for a shape before running.

Freivalds verification#

For each returned tile C, the SDK draws a random binary vector r ∈ {0,1}ᴺ and checks

That's three matrix–vector products — O(n²) instead of the O(n³) GEMM. A wrong result passes a single round with probability ≤ ½, so k rounds (freivalds_rounds, default 5) bound false-accepts at 2⁻ᵏ.

Floating-point tolerance uses Higham's bound ε = γ_K · ‖A‖∞ · ‖B‖∞ with γ_K = K·u / (1 − K·u) for the dtype's unit roundoff u, plus a relative_discrepancy_threshold guard against zero-work fraud on tiny inputs.

On failure the SDK raises FraudDetectedError, cancels the HODL invoice and submits a signed FreivaldsFraudProof. Building blocks are public: freivalds_verify, FreivaldsVerifier, FraudProofBuilder, verify_fraud_proof.

L402 payments & escrow#

Every tile is paid with a Lightning HODL invoice: funds lock when the task is dispatched and only settle (the preimage is released) after Freivalds passes. Failed verification cancels the invoice. Workers enforce payment with an L402 gate — tasks without a valid held invoice are rejected before any GPU memory is allocated.

To pay from your own LND node:

export MATRIX_LND_PAYER_ENABLED=true
export CONSUMER_LND_REST_URL=https://127.0.0.1:8081
export CONSUMER_LND_MACAROON_PATH=~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon
export CONSUMER_LND_TLS_PATH=~/.lnd/tls.cert

Cap spend with max_budget_sats (enforced by BudgetController). The settlement layer takes a 2% routing fee.

Confidential computing (TEE)#

Freivalds guarantees correctness; TEEs add privacy. With require_confidential_compute=True (the default) the SDK only dispatches to workers presenting valid hardware attestation, verifies the evidence chain, binds it to a session nonce and encrypts tiles end-to-end with AES-256-GCM.

# Only AMD SEV-SNP enclaves
client = MatrixComputeClient(required_tee_type="amd-sev-snp")

# Public data, any worker (disables attestation + E2E encryption)
client = MatrixComputeClient(require_confidential_compute=False)

Attestation failures raise AttestationError subclasses such as AttestationChainInvalidError, AttestationNonceMismatchError or AttestationMeasurementMismatchError. Worker-side setup is under worker configuration.

Errors#

All exceptions derive from MatrixComputeError:

NoWorkersFoundError usually means your min_worker_vram_mb, max_price_per_gflop or TEE requirement is stricter than anything currently online — check the live dashboard.

1-command install#

The installer detects NVIDIA GPUs, AMD ROCm, AMD SEV-SNP, Intel TDX or CPU-only hosts, checks your container runtime, generates a worker Nostr keypair (stored in ~/.matrix/worker.env), enables outbound-only NAT traversal and renders the operator dashboard with a Lightning QR code.

# Linux / macOS
curl -sSL https://matrix-compute.com/worker.sh | bash

# Windows PowerShell
irm https://matrix-compute.com/worker.ps1 | iex

Docker deployment#

GPU images need the NVIDIA Container Toolkit. Build from the workspace root of the matrix-dockerimages repo:

docker build -f matrix-dockerimages/compute-node/Dockerfile.gpu -t matrix-compute-node:gpu .

docker run -d --name matrix-worker --gpus all \
  -p 50051:50051 \
  -e MATRIX_WORKER_GPU_DEVICE_INDEX=0 \
  -e MATRIX_WORKER_DTYPE_PREFERENCE=fp16 \
  -e MATRIX_WORKER_LIGHTNING_ROUTING_PUBKEY=<your-66-hex-node-pubkey> \
  -e MATRIX_WORKER_SATS_PER_GFLOP=0.0005 \
  matrix-compute-node:gpu

A CPU image (compute-node/Dockerfile) is also available. For a full local network (relay + settlement + worker) use docker compose -f matrix-dockerimages/docker-compose.yml up -d.

Worker configuration#

Each setting accepts MATRIX_*, MATRIX_WORKER_* or the unprefixed name.

NAT traversal#

Home connections rarely accept inbound gRPC. With MATRIX_NAT_MODE=reverse_tunnel (the installer default) the node dials the relay's gRPC tunnel service and keeps it alive with heartbeats (MATRIX_TUNNEL_HEARTBEAT_INTERVAL_SECONDS, default 30). The relay only matches consumers to tunnelled workers whose tunnel is currently active. Workers with a public IP can use direct mode and expose 50051 for lower latency.

Bonds & tiers#

Every announcement carries a bond_status with your staked sats. The bond is your skin in the game: a valid fraud proof slashes it. Tiers:

• PROBATIONARY — new workers; auto-bond sweeps 50–100% (auto_bond_percent) of earnings into the bond until the graduation threshold (default 100,000 sats).
• FULL_TIER — fully bonded workers.
• BLACKLISTED / DEACTIVATED — slashed or retired keys.

Setup & authentication#

Add to claude_desktop_config.json, Cursor's mcp.json or Antigravity's MCP settings:

{
  "mcpServers": {
    "matrix-compute": {
      "command": "uvx",
      "args": ["matrix-compute-mcp", "--live-mode"],
      "env": {
        "MATRIX_L402_MACAROON": "<your-l402-macaroon>"
      }
    }
  }
}

Auth precedence: L402 macaroon → trial API key → offline mock trial. A Docker image is also provided (matrix-dockerimages/mcp).

Tools reference#

Matrix inputs accept a file path (.npy, .npz, .safetensors) or an inline 2D JSON array.

Typical agent loop: get_network_status → estimate_job_cost → confirm budget → execute_distributed_matmul.

AI primitives (matrix_compute_mcp.ai)#

The same verified building blocks the MCP tools use, importable from Python:

from matrix_compute_mcp.ai import (
    DistributedLinear,            # drop-in torch.nn.Linear, verified fwd + bwd
    DistributedLoRALinear,        # LoRA adapter layer
    distributed_cosine_similarity,
    distributed_pca_svd,
)

scores, indices = distributed_cosine_similarity(queries, corpus_embeddings, top_k=10)
layer = DistributedLinear(in_features=4096, out_features=4096)
lora = DistributedLoRALinear(in_features=4096, out_features=4096, r=16, lora_alpha=32.0)
U, S, Vt = distributed_pca_svd(embeddings, k=32, method="randomized")

Kind 30000 worker announcements#

Workers publish NIP-33 parameterised replaceable events keyed by (pubkey, d). The newest created_at wins; ties break on the lowest event id. Key fields are duplicated as tags for cheap filtering; the full WorkerAnnouncePayload is JSON in content. Relays read tags first and fall back to content per attribute.

{
  "kind": 30000,
  "pubkey": "<worker secp256k1 pubkey>",
  "created_at": 1761350400,
  "tags": [
    ["d", "matrix-compute-worker"],
    ["p2p", "/ip4/203.0.113.7/tcp/50051"],
    ["lightning", "<66-hex node pubkey>"],
    ["gpu_model", "NVIDIA GeForce RTX 4090"],
    ["vram_mb", "24564"],
    ["sats_per_gflop", "0.0005"],
    ["min_task_sats", "10"],
    ["staked_sats", "100000"],
    ["nat_mode", "reverse_tunnel"],
    ["tee", "true"], ["tee_type", "nvidia-cca"]
  ],
  "content": "{\"event\":\"WORKER_ANNOUNCE\",\"hardware\":{\"gpu_model\":...,\"peak_fp32_tflops\":82.6,...},\"pricing\":{...},\"bond_status\":{...}}"
}

Relay API#

One port (default 8008) multiplexes WebSocket and HTTP. All HTTP responses send Access-Control-Allow-Origin: *, so browsers can query them directly — this site's dashboard does exactly that.

curl -s https://relay.matrix-compute.net/rpc -H 'Content-Type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "QUERY_WORKERS",
  "params": { "min_vram_mb": 16384, "max_price_sats_per_gflop": 0.001,
              "required_slots": 4, "require_tee": true, "required_tee_type": "nvidia-cca" }
}'

The response lists matched_workers with worker_pubkey, p2p_multiaddr, sats_per_gflop, reputation_score, tee_type and nat_mode. Tile transfer itself uses the gRPC MatrixComputeService defined in matrix-contracts/proto/compute_service.proto.

Fraud proofs#

A FreivaldsFraudProof proves max|A(Br) − Cr| > ε for a result the worker signed:

The settlement oracle independently re-verifies the vectors in O(M) before slashing.

Batched LLM inference & embedding search#

Scoring M queries against an N-document corpus is a single (M×D)·(D×N) GEMM — enormous output, small inner dimension. That's the ideal shape for OUTPUT_GRID_2D: each worker returns a disjoint block of scores, nothing is downloaded twice and nothing is summed locally.

import numpy as np
from matrix_compute_mcp.ai import distributed_cosine_similarity

queries = np.load("queries.npy").astype(np.float32)      # (200_000, 1024)
corpus  = np.load("corpus.npy").astype(np.float32)       # (5_000_000, 1024)
scores, idx = distributed_cosine_similarity(queries, corpus, top_k=10)

The same pattern covers offline LLM batch inference: stack prompt activations into one big matrix per layer and use DistributedLinear or client.matmul(..., partitioning_strategy="output_grid_2d").

Iterative scientific solvers#

Power iteration, PageRank and spectral methods apply the same matrix hundreds of times. Re-uploading A every step would be WAN-bound, so the SDK leases worker VRAM: A is uploaded once, kept resident for lease_ttl_seconds, and only the vector travels each step. A random spot_check_probability fraction of steps is Freivalds-verified via verify_iterative_step.

from matrix_compute import MatrixComputeClient

with MatrixComputeClient(lease_ttl_seconds=1800, spot_check_probability=0.1) as client:
    v = client.power_iteration(A, iterations=500, normalize=True)
dominant_eigenvalue = v @ (A @ v)

For top-k decompositions use distributed_pca_svd(X, k, method="power_iteration").

Autonomous L402 agents#

An agent with a Lightning wallet can buy compute without any human account: configure the MCP server with an L402 macaroon, then let the agent call estimate_job_cost before execute_distributed_matmul so it can reason about spend. Set max_budget_sats on the underlying client to hard-cap what any single session can pay.

Edge & constrained-device offloading#

A Raspberry Pi can't run a 30k×30k GEMM, but it can verify one: Freivalds needs only three matrix–vector products. Batch frames from an edge camera into photogrammetry / neural-field matrices, offload with distributed_matmul, and keep the O(n²) verification local. Use fp16 to halve upload size, and OUTER_PRODUCT_1D if your uplink is the bottleneck.