malt

README

MALT Core

MALT is an SDK and protocol implementation for arc-granularity graph data authentication.

MALT keeps payload bytes in content-addressed storage (CAS) and authenticates typed relations with vector-commitment backends. A client verifies:

trusted root + typed resolve/read request -> result + ProofList

The repository is deliberately application- and deployment-neutral. It does not contain a gateway service, ArcTable implementation, CAS backend, command line client, daemon, UnixFS model, or website.

Documentation · Architecture · Resolve/read contracts · ProofList · Compatibility · v0.0.6 release · Roadmap

Boundary

MALT core owns:

• canonical segment and arc semantics;
• typed map/list roots and CID rules;
• map/list commitment, proof, and verification algorithms;
• malt.resolve/v0alpha1 and malt.read/v0alpha1 values and JSON Schemas;
• ProofList generation/verification semantics;
• portable mutation and receipt values;
• untrusted resolve/read/apply composition over caller-injected capabilities;
• native Go and browser/WASM verification.

MALT core does not own:

• HTTP routing or service policy;
• ArcTable, KV, SQL, cache, or durable materialization implementations;
• CAS access or payload lifecycle;
• trusted-root storage, freshness, publication, or multi-writer policy;
• UnixFS, TypeScript object syntax, or another application model;
• a CLI, client daemon, managed gateway, or website.

Those responsibilities are split across independent repositories:

Repository	Responsibility
DeWebProtocol/malt-client	CLI/client daemon, trusted roots, local verification, UnixFS planning and payload binding
DeWebProtocol/gateway	Untrusted resolve/read/apply execution, ArcTable/KV/CAS, service and deployment policy
DeWebProtocol/web	Browser client, local WASM verification, public website and tutorials

Core composition

flowchart LR
  app["Application client"] --> request["resolve/read request"]
  request --> gateway["Untrusted executor"]
  gateway --> result["result + ProofList"]
  result --> verify["MALT local verifier"]
  trusted["Client-selected trusted root"] --> verify
  verify --> decision["accept / reject"]

  gateway --> store["Caller-owned ArcSet materializer"]
  gateway --> cas["Caller-owned CAS"]

An executor may use an ArcTable to accelerate candidate selection, including longest-prefix discovery. The verifier proves the returned derivation; it does not prove that the executor selected the unique or longest possible path. This is intentional existential resolution semantics.

The core exposes only the minimal auth/arcset/materializer.Store capability needed by proof-generation algorithms. Implementations and persistence policy remain outside this module. The included memory implementation exists for conformance tests and examples, not deployment.

Install

go get github.com/dewebprotocol/malt@v0.0.6

Verify a resolve result

verifier, err := sdkverifier.NewDefault()
if err != nil {
    return err
}

err = verifier.VerifyResolve(ctx, protocol.ResolveVerification{
    Request: request, // independently constructed by the client
    Result:  result,  // untrusted gateway response
})

Verification performs no network, CAS, ArcTable, filesystem, or gateway I/O. Applications that consume payload bytes must additionally hash those bytes against the authenticated CID. Application-specific range composition belongs in the application client.

Packages

Package	Role
module root malt	Stable typed resolve/read/query values and verification entry points
auth/arcset	Canonical typed arcs, targets, sets, and iteration
auth/commitment	KZG/IPA commitment capabilities
auth/semantic	Map/list semantic contracts and reference algorithms
auth/proof	ProofList/evidence formats
auth/verifier	Storage-free ProofList verification
protocol	Versioned serialized resolve/read profiles and schemas
mutation	Portable mutation and receipt values
execution	Untrusted resolve/read/apply composition
graph	Resolver/writer algorithms over injected capabilities
sdk/verifier	Client-facing local verification facade
artifact	Frozen malt.artifact/v0alpha2 compatibility decoder/verifier
cmd/malt-verifier-wasm	Browser verifier build entry point

Development

go test ./...
go vet ./...
go build -buildvcs=false ./...
scripts/build-verifier-wasm.sh dist/verifier

MALT is pre-v1 and experimental. Pin exact releases and reject unknown protocol profiles. See compatibility policy.

Documentation

Overview

Package malt exposes the application-neutral MALT core facade.

The facade is intentionally small. Client/application adapters translate domain operations into typed map/list queries and semantic mutations, while runtime state placement, ArcTable namespaces, HTTP transport, and payload CAS access remain outside the caller-visible contract.

Index

• Constants
• Variables
• func IsQueryNotFound(err error) bool
• func VerifyRead(ctx context.Context, req ReadRequest, result ReadResult, ...) error
• func VerifyResolve(ctx context.Context, req ResolveRequest, result ResolveResult, ...) error
• type Mutation
• type ProofVerifier
• type Query
  • func ListIndexQuery(index uint64) Query
  • func ListRangeQuery(start uint64, end *uint64) (Query, error)
  • func MapKeyQuery(rawKey string) (Query, error)
  • func (q Query) String() string
  • func (q Query) Validate() error
• type QueryKind
• type ReadRequest
• type ReadResult
• type Reader
• type ResolveRequest
  • func (r ResolveRequest) Validate() error
• type ResolveResult
• type Resolver
• type SegmentPath
  • func NewSegmentPath(segments []string) (SegmentPath, error)
  • func ParseSegmentPath(raw string) (SegmentPath, error)
  • func (p SegmentPath) Consume(prefix SegmentPath) (SegmentPath, bool)
  • func (p SegmentPath) Empty() bool
  • func (p SegmentPath) HasPrefix(prefix SegmentPath) bool
  • func (p SegmentPath) Segments() []string
  • func (p SegmentPath) String() string
• type WriteResult

Constants

const PathSeparator = "/"

PathSeparator is the canonical textual separator for MALT segment paths. Transports may carry segments without using this textual projection.

Variables

var (
	// ErrInvalidQuery is returned when a typed query is incomplete or malformed.
	ErrInvalidQuery = errors.New("invalid MALT query")
	// ErrQueryNotFound is returned when a query has no authenticated target.
	ErrQueryNotFound = errors.New("MALT query target not found")
	// ErrVerifierRejected is returned when proof verification returns false.
	ErrVerifierRejected = errors.New("MALT verifier rejected read result")
)

Functions

func IsQueryNotFound

func IsQueryNotFound(err error) bool

IsQueryNotFound reports whether err represents an unauthenticated or absent query target.

func VerifyRead

func VerifyRead(ctx context.Context, req ReadRequest, result ReadResult, verifier ProofVerifier) error

VerifyRead validates the complete verifier-facing read contract.

func VerifyResolve

func VerifyResolve(ctx context.Context, req ResolveRequest, result ResolveResult, verifier ProofVerifier) error

VerifyResolve validates a complete path-resolution result against the caller-selected root and segment sequence. ProofList is evidence for the result, not the source of the caller's trust inputs.

Types

type Mutation

type Mutation = mutation.SemanticMutation

Mutation is the portable semantic mutation contract. Runtime state placement and publication policy are deliberately absent.

type ProofVerifier

type ProofVerifier interface {
	VerifyProofList(context.Context, prooflist.ProofList) (bool, error)
}

ProofVerifier is the portable verifier surface consumed by clients. An implementation must not require ArcTable, CAS, server, or executor state.

type Query

type Query struct {
	Kind  QueryKind
	Key   arcset.Path
	Index uint64
	Start uint64
	End   *uint64
}

Query is a single typed arc query. Multi-step application traversal is composed by clients/application adapters from these primitive operations.

func ListIndexQuery

func ListIndexQuery(index uint64) Query

ListIndexQuery creates a stable-indexed list query.

func ListRangeQuery

func ListRangeQuery(start uint64, end *uint64) (Query, error)

ListRangeQuery creates a measured-list range query over [start, end). A nil end means the authenticated total size.

func MapKeyQuery

func MapKeyQuery(rawKey string) (Query, error)

MapKeyQuery creates an exact keyed-map query.

func (Query) String

func (q Query) String() string

String returns the current v0alpha1 query label used in ProofList evidence.

func (Query) Validate

func (q Query) Validate() error

Validate checks the typed query contract.

type QueryKind

type QueryKind string

QueryKind identifies one application-neutral semantic query.

const (
	// QueryMapKey authenticates one keyed map relation.
	QueryMapKey QueryKind = "map_key"
	// QueryListIndex authenticates one stable list index.
	QueryListIndex QueryKind = "list_index"
	// QueryListRange authenticates one measured-list byte range.
	QueryListRange QueryKind = "list_range"
)

type ReadRequest

type ReadRequest struct {
	Root  cid.Cid
	Query Query
}

ReadRequest binds a typed query to a caller-supplied trusted root.

type ReadResult

type ReadResult struct {
	Target    cid.Cid
	Segments  []cid.Cid
	ProofList prooflist.ProofList
}

ReadResult is the verifier-facing result of one typed query. Target is the authenticated relation target. Segments is populated only for measured-list ranges and remains ordered as authenticated by ProofList.

type Reader

type Reader interface {
	Read(context.Context, ReadRequest) (ReadResult, error)
}

Reader is the application-neutral root-relative read port.

type ResolveRequest

type ResolveRequest struct {
	Root     cid.Cid
	Segments []string
}

ResolveRequest binds one canonical segment path to a caller-supplied trusted root. Applications append reserved coordinates such as @payload explicitly; an empty segment sequence always denotes root identity.

func (ResolveRequest) Validate

func (r ResolveRequest) Validate() error

Validate checks the transport-neutral resolution request.

type ResolveResult

type ResolveResult struct {
	Target    cid.Cid
	ProofList prooflist.ProofList
}

ResolveResult is the authenticated target plus the ordered evidence for one complete segment-path derivation.

type Resolver

type Resolver interface {
	Resolve(context.Context, ResolveRequest) (ResolveResult, error)
}

Resolver is the application-neutral path-resolution port. Implementations execute against untrusted runtime state; clients call VerifyResolve before accepting the returned target.

type SegmentPath

type SegmentPath struct {
	// contains filtered or unexported fields
}

SegmentPath is an immutable application-neutral sequence of MALT path segments. Applications and transports decide how their own path syntax maps to segments; MALT owns the canonical segment-to-arc projection.

func NewSegmentPath

func NewSegmentPath(segments []string) (SegmentPath, error)

NewSegmentPath validates and clones a segment sequence. Segments are non-empty UTF-8 strings and must not contain the canonical separator.

func ParseSegmentPath

func ParseSegmentPath(raw string) (SegmentPath, error)

ParseSegmentPath parses the canonical textual projection used by the reference slash-path adapters. The empty string denotes the root path.

func (SegmentPath) Consume

func (p SegmentPath) Consume(prefix SegmentPath) (SegmentPath, bool)

Consume removes a segment-aligned prefix.

func (SegmentPath) Empty

func (p SegmentPath) Empty() bool

Empty reports whether the path denotes the caller-supplied root.

func (SegmentPath) HasPrefix

func (p SegmentPath) HasPrefix(prefix SegmentPath) bool

HasPrefix reports whether prefix is a segment-aligned prefix of p.

func (SegmentPath) Segments

func (p SegmentPath) Segments() []string

Segments returns a cloned segment slice.

func (SegmentPath) String

func (p SegmentPath) String() string

String returns the canonical textual projection.

type WriteResult

type WriteResult = mutation.WriteReceipt

WriteResult is the current v0alpha1 result-root receipt.