arc

README

Arc

A minimal, canonical Go library for the Arc protocol primitives.

Overview

Arc is a protocol where everything is a keypair, and keypairs with purpose become identities. This repository defines the foundational primitives that all Arc-compatible systems share.

This repo is intentionally minimal. It defines the protocol, not any particular implementation of storage, relay, or application logic. Those belong in separate repositories that import this foundation.

The Primitives

Arc has exactly four primitives:

Primitive	Purpose	Size
PublicKey	A keypair's identity on the wire	32 bytes (Ed25519)
Reference	A content-addressed pointer	32 bytes (SHA-256)
Content	An immutable blob	Arbitrary bytes
Message	A signed envelope between keypairs	Structured

Message Structure

Message {
  from:         PublicKey    // Sender
  to:           PublicKey    // Recipient
  content:      Reference    // Hash of content
  content_type: string       // MIME type
  timestamp:    int64        // Unix milliseconds
  signature:    bytes        // 64-byte Ed25519 signature
}

Canonical Serialization

Arc defines canonical byte representations for all types. This ensures that references and signatures are computed identically across any language or implementation.

Message (canonical bytes):

from.key          (32 bytes)
|| to.key         (32 bytes)
|| content.hash   (32 bytes)
|| content_type_len (4 bytes, big-endian uint32)
|| content_type   (UTF-8 bytes)
|| timestamp      (8 bytes, big-endian int64, Unix milliseconds)
|| signature      (64 bytes)

Signing payload is canonical bytes without the signature.

Message reference is SHA-256(canonical bytes) — includes signature.

Installation

go get github.com/gezibash/arc

Usage

package main

import (
    "fmt"

    "github.com/gezibash/arc/pkg/content"
    "github.com/gezibash/arc/pkg/identity"
    "github.com/gezibash/arc/pkg/message"
)

func main() {
    // Create identities
    alice, _ := identity.Generate()
    bob, _ := identity.Generate()

    // Create content
    data := []byte(`{"hello": "world"}`)
    c := content.New(data)

    // Create and sign message
    msg := message.New(alice.PublicKey(), bob.PublicKey(), c.Hash(), "application/json")
    message.Sign(&msg, alice)

    // Verify
    valid, _ := message.Verify(msg)
    fmt.Println("Valid:", valid) // true
}

Repository Structure

arc/
├── pkg/
│   ├── identity/    # Ed25519 keypair operations
│   ├── reference/   # SHA-256 content addressing
│   ├── message/     # Signed message envelopes
│   ├── content/     # Content with cached hash
│   └── errs/        # Error definitions
├── go.mod
└── README.md

License

MIT