"""NIP-90 ingress (profile `nip90-ingress`): the bytes a DVM gateway speaks.
Three things are pinned here and in vectors/nip90.json, nothing else:
1. A request (kind 5000-5999) parses to one `ParsedRequest`: `i` tags are
inputs, `param` tags a str->str map (last wins), `output` the mime,
`bid` msat, `relays` only ws/wss entries.
2. A parsed request maps to a job descriptor by executor, chosen in the
order zk, llm, bacalhau, agent, then WASM - from the kind first, then
the `executor`/`engine` params. The WASM job's `input.sha256` is the
sha256 of the canonical JSON of {prompt, inputs, params}.
3. Feedback is kind 7000 with tags e, p, status[, extra]; a result is
kind request+1000 with tags e, p, request (the request event in the
protocol's canonical form - constants.json `canonical.form`),
then amount / commit when non-zero.
The job descriptor is what the gateway hands its compute compartment; a
second node may run a different executor set but MUST produce these
descriptors for these requests, since the result's `request` tag and
`commit` are compared against them downstream.
"""
from __future__ import annotations
import json
import math
from typing import Any, Mapping, Optional, Sequence, TypedDict
from ..crypto import crypto
from ..storage import store
from ..wire.interfaces import EventLike, NostrEvent
FEEDBACK_KIND: int = 7000
REQUEST_RANGE: tuple[int, int] = (5000, 6000)
RESULT_RANGE: tuple[int, int] = (6000, 7000)
FEEDBACK_STATES: tuple[str, ...] = ('payment-required', 'processing', 'error', 'success', 'partial')
# The kinds the reference gateway answers by default. A node may narrow this
# in its configuration; it must not answer a kind it does not list.
DEFAULT_KINDS: tuple[int, ...] = (5000, 5001, 5050, 5055, 5100, 5200, 5300, 5905)
ZK_KINDS: tuple[int, ...] = (5055, 5905)
ZK_NAMES: tuple[str, ...] = ('zk-verify-groth16', 'zk', 'zkvm')
LLM_KIND: int = 5050
LLM_NAMES: tuple[str, ...] = ('llm', 'ai', 'inference', 'vllm', 'ollama')
TRANSCODE_KIND: int = 5201
MEDIA_NAMES: tuple[str, ...] = ('ffmpeg', 'media-transcode', 'transcode', 'video-transcode')
BACALHAU_NAMES: tuple[str, ...] = ('bacalhau', 'docker', 'container')
AGENT_NAMES: tuple[str, ...] = ('agent', 'react')
DEFAULT_FUEL: int = 2500000000
DEFAULT_MODEL: str = 'meta-llama/Llama-3.3-70B-Instruct'
def _int_param(params: Mapping[str, str], key: str, default: int) -> int:
"""An integer param; a non-integer value is a refusal, not a rounding."""
raw = params.get(key)
if raw is None:
return default
try:
return int(str(raw).strip())
except ValueError:
raise DVMError('param %s must be an integer, got %r' % (key, raw))
[docs]class DVMError(ValueError):
pass
[docs]class ParsedRequest(TypedDict):
id: str
pubkey: str
kind: int
content: str
inputs: list[list[str]]
params: dict[str, str]
output_mime: str
bid_msat: int
relays: list[str]
[docs]class ZkProof(TypedDict, total=False):
pi_a: Sequence[str]
pi_b: Sequence[Sequence[str]]
pi_c: Sequence[str]
protocol: str
curve: str
[docs]class LLMSampling(TypedDict, total=False):
max_tokens: int
temperature: float
top_p: float
seed: int
[docs]class LLMGrammar(TypedDict, total=False):
type: str
definition: str
json_schema: Any
response_format: str
guided_regex: str
[docs]class LLMMessage(TypedDict, total=False):
role: str
content: str
[docs]class WasmModule(TypedDict, total=False):
runtime: str
sha256: str
url: str
[docs]class StorageMount(TypedDict, total=False):
cas_provider: str
source_cid: str
mount_path: str
[docs]class JobVerify(TypedDict, total=False):
mode: str
proof_system: str
sample_rate: float
[docs]class Job(TypedDict, total=False):
executor: str
module: WasmModule | Mapping[str, Any]
input: ZkInput | WasmInput | MediaInput | Mapping[str, Any]
verify: JobVerify | Mapping[str, Any]
fuel_max: int
model: str
prompt: str
messages: list[LLMMessage | Mapping[str, Any]]
sampling: LLMSampling | Mapping[str, Any]
grammar: LLMGrammar | Mapping[str, Any]
engine: str
image: str
entrypoint: list[str]
storage_mounts: list[StorageMount | Mapping[str, Any]]
resources: Mapping[str, int | str | float]
task: str
max_steps: int
wasi_profile: str
nonce: str
blob_store: Any
blossom_servers: Sequence[str]
[docs]def is_request(ev: EventLike) -> bool:
k = ev.get('kind', 0)
return isinstance(k, int) and REQUEST_RANGE[0] <= k < REQUEST_RANGE[1]
[docs]def is_result(ev: EventLike) -> bool:
k = ev.get('kind', 0)
return isinstance(k, int) and RESULT_RANGE[0] <= k < RESULT_RANGE[1]
[docs]def result_kind(request_kind: int) -> int:
return request_kind + 1000
[docs]def parse_request(ev: EventLike) -> ParsedRequest:
inputs: list[list[str]] = []
params: dict[str, str] = {}
relays: list[str] = []
output_mime = 'text/plain'
bid_msat = 0
tags = ev.get('tags', [])
for t in tags if isinstance(tags, list) else []:
if not t or not isinstance(t, list):
continue
name = t[0]
if name == 'i' and len(t) > 1:
inputs.append([str(x) for x in t[1:]])
elif name == 'param' and len(t) > 2:
params[str(t[1])] = str(t[2])
elif name == 'output' and len(t) > 1:
output_mime = str(t[1])
elif name == 'bid' and len(t) > 1:
msats = store.ascii_int(t[1])
if msats is not None:
bid_msat = msats
elif name == 'relays':
relays.extend(str(r) for r in t[1:] if str(r).startswith(('ws://', 'wss://')))
kind = ev.get('kind', 5000)
return {
'id': str(ev.get('id', '')),
'pubkey': str(ev.get('pubkey', '')),
'kind': kind if isinstance(kind, int) else 5000,
'content': str(ev.get('content', '')),
'inputs': inputs,
'params': params,
'output_mime': output_mime,
'bid_msat': bid_msat,
'relays': relays,
}
# ---- executor selection --------------------------------------------------------
def _names(p: ParsedRequest) -> tuple[str, str]:
return p['params'].get('executor', '').lower(), p['params'].get('engine', '').lower()
[docs]def is_zk(p: ParsedRequest) -> bool:
e, g = _names(p)
return p['kind'] in ZK_KINDS or e in ZK_NAMES or g in ZK_NAMES
[docs]def is_llm(p: ParsedRequest) -> bool:
e, g = _names(p)
return p['kind'] == LLM_KIND or e in LLM_NAMES or g in LLM_NAMES
[docs]def is_bacalhau(p: ParsedRequest) -> bool:
e, g = _names(p)
return (5900 <= p['kind'] < 6000 and not is_zk(p)) or e in BACALHAU_NAMES or g in BACALHAU_NAMES
[docs]def is_agent(p: ParsedRequest) -> bool:
e, g = _names(p)
return e in AGENT_NAMES or g in AGENT_NAMES
[docs]def executor_of(p: ParsedRequest) -> str:
if is_zk(p):
return 'zk'
if is_llm(p):
return 'llm'
if is_media(p):
return 'ffmpeg'
if is_bacalhau(p):
return 'bacalhau'
if is_agent(p):
return 'agent'
return 'wasm'
# ---- job descriptors -----------------------------------------------------------
def _json_or(text: str, open_ch: str) -> Any:
if text.startswith(open_ch):
try:
return json.loads(text)
except ValueError:
return text
return text
[docs]def zk_job(p: ParsedRequest, fuel_max: int = DEFAULT_FUEL) -> Job:
"""Groth16 proof verification: proof, public inputs and vk from content or `i` tags."""
exec_param, _ = _names(p)
target = 'zk-verify-groth16' if ('groth16' in exec_param or p['kind'] in ZK_KINDS) else (exec_param or 'zk-verify-groth16')
curve = p['params'].get('curve', 'bn254')
proof: Any = None
inputs: list[Any] = []
vk: Any = None
vk_sha256: Optional[str] = p['params'].get('vk_sha256')
content = p['content'].strip()
if content.startswith('{') and content.endswith('}'):
try:
c = json.loads(content)
except ValueError:
c = None
if isinstance(c, dict):
proof = c.get('proof')
pi = c.get('public_inputs', [])
inputs = list(pi) if isinstance(pi, list) else [pi]
if 'curve' in c:
curve = str(c['curve'])
if 'vk' in c:
vk = c['vk']
if 'vk_sha256' in c:
vk_sha256 = str(c['vk_sha256'])
for inp in p['inputs']:
if len(inp) < 2:
continue
val, role = inp[0], inp[1].lower()
if role in ('proof', 'zk-proof'):
proof = _json_or(val, '{')
elif role in ('inputs', 'public_inputs'):
got = _json_or(val, '[')
inputs = got if isinstance(got, list) else [val]
elif role in ('input', 'public_input'):
inputs.append(val)
elif role in ('vk', 'verification_key'):
vk = _json_or(val, '{')
zk_input: ZkInput = {'request_id': p['id'], 'curve': curve, 'proof': proof or {}, 'public_inputs': inputs}
if vk is not None:
zk_input['vk'] = vk
if vk_sha256 is not None:
zk_input['vk_sha256'] = vk_sha256
return {
'executor': target,
'module': {'runtime': target, 'sha256': crypto.sha256(('nip90-zk-verify-%s' % curve).encode())},
'input': zk_input,
'verify': {'mode': 'proof', 'proof_system': target},
'fuel_max': fuel_max,
}
[docs]def llm_job(p: ParsedRequest, fuel_max: int = DEFAULT_FUEL) -> Job:
"""An inference request: messages, sampling and an optional grammar."""
params = p['params']
model = params.get('model', DEFAULT_MODEL)
prompt = p['content']
messages: list[LLMMessage | Mapping[str, Any]] = []
for inp in p['inputs']:
if not inp:
continue
val = inp[0]
role = inp[1].lower() if len(inp) > 1 else 'text'
if role == 'json' and val.startswith('{'):
try:
j = json.loads(val)
except ValueError:
continue
if isinstance(j, dict):
if 'messages' in j and isinstance(j['messages'], list):
messages.extend(j['messages'])
elif 'prompt' in j:
prompt = str(j['prompt'])
elif role in ('text', 'prompt') and not prompt:
prompt = val
if not messages and prompt:
messages = [{'role': 'user', 'content': prompt}]
sampling: LLMSampling = {
'max_tokens': _int_param(params, 'max_tokens', 512),
'temperature': float(params.get('temperature', 0.7)),
'top_p': float(params.get('top_p', 1.0)),
}
if 'seed' in params:
seed = store.ascii_int(params['seed'])
if seed is not None:
sampling['seed'] = seed
grammar: LLMGrammar = {}
if 'schema' in params:
sv = params['schema']
grammar['type'] = 'json_schema'
grammar['definition'] = sv
grammar['json_schema'] = _json_or(sv, '{')
elif params.get('response_format') == 'json_object':
grammar['type'] = 'json_schema'
grammar['definition'] = '{"type": "object"}'
grammar['response_format'] = 'json_object'
elif 'response_format' in params:
grammar['response_format'] = params['response_format']
if 'regex' in params:
grammar['type'] = 'regex'
grammar['definition'] = params['regex']
grammar['guided_regex'] = params['regex']
verify = params.get('verify', 'schema-bounds' if ('schema' in params or 'response_format' in params) else 'delivery')
return {
'executor': 'llm', 'model': model, 'prompt': prompt, 'messages': messages,
'sampling': sampling, 'grammar': grammar, 'verify': {'mode': verify}, 'fuel_max': fuel_max,
}
[docs]def bacalhau_job(p: ParsedRequest, fuel_max: int = DEFAULT_FUEL) -> Job:
"""A container job: image, entrypoint, Blossom-mounted inputs, resources."""
params = p['params']
entry = params.get('entrypoint', '/bin/sh -c')
mounts: list[StorageMount | Mapping[str, Any]] = [
{'cas_provider': 'blossom', 'source_cid': inp[0], 'mount_path': inp[2] if len(inp) > 2 else '/inputs'}
for inp in p['inputs'] if inp
]
return {
'executor': 'bacalhau', 'engine': 'docker',
'image': params.get('image', 'alpine:latest'),
'entrypoint': entry.split(),
'storage_mounts': mounts,
'resources': {
'cpu': _int_param(params, 'cpu', 2), 'gpu': _int_param(params, 'gpu', 0),
'memory_gib': float(params.get('memory_gib', 4.0)),
'timeout_seconds': _int_param(params, 'timeout', 300),
},
'verify': {'mode': params.get('verify', 'delivery')},
'fuel_max': fuel_max,
}
[docs]def agent_job(p: ParsedRequest, fuel_max: int = DEFAULT_FUEL) -> Job:
"""A ReAct agent task with a step cap."""
return {
'executor': 'agent', 'task': p['content'],
'max_steps': _int_param(p['params'], 'max_steps', 25),
'verify': {'mode': 'delivery'}, 'fuel_max': fuel_max,
}
[docs]def wasm_job(p: ParsedRequest, executor: str = 'wasm', fuel_max: int = DEFAULT_FUEL) -> Job:
"""The deterministic WASM job. The module is named by the requester
(`param module <sha256>`, optional `param module_url`); with none named
there is nothing real to run and a gateway refuses rather than inventing."""
encoded = json.dumps({'prompt': p['content'], 'inputs': p['inputs'], 'params': p['params']},
sort_keys=True, separators=(',', ':'))
module: WasmModule = {'runtime': executor}
sha = p['params'].get('module', '').strip().lower()
if sha:
module['sha256'] = sha
if p['params'].get('module_url'):
module['url'] = p['params']['module_url']
return {
'executor': executor, 'module': module,
'input': {'request_id': p['id'], 'sha256': crypto.sha256(encoded.encode()), 'raw': encoded},
'wasi_profile': 'fleetmesh-wasi-v1', 'nonce': p['id'],
'verify': {'mode': 'none'}, 'fuel_max': fuel_max,
}
[docs]def request_to_job(ev: EventLike, executor: str = 'wasm', fuel_max: int = DEFAULT_FUEL) -> Job:
"""Map a NIP-90 request into the job descriptor the mesh runs."""
p = parse_request(ev)
which = executor_of(p)
if which == 'zk':
return zk_job(p, fuel_max)
if which == 'llm':
return llm_job(p, fuel_max)
if which == 'ffmpeg':
return media_job(p, fuel_max)
if which == 'bacalhau':
return bacalhau_job(p, fuel_max)
if which == 'agent':
return agent_job(p, fuel_max)
return wasm_job(p, executor, fuel_max)
# ---- the events a gateway emits -----------------------------------------------
[docs]def feedback(signer_sk: str, request_ev: EventLike, status: str, now: int, extra: str = '',
extra_tags: Optional[Sequence[Sequence[str]]] = None) -> NostrEvent:
"""Kind 7000: tags e, p, status[, extra]; content is extra or the status."""
if status not in FEEDBACK_STATES:
raise DVMError('unknown feedback status %r' % status)
tags: list[list[str]] = [['e', str(request_ev.get('id', ''))], ['p', str(request_ev.get('pubkey', ''))], ['status', status]]
if extra:
tags[-1].append(extra)
for xt in extra_tags or []:
if xt:
tags.append([str(x) for x in xt])
return store.make_signed_event(signer_sk, now, FEEDBACK_KIND, tags, extra or status)
[docs]def result(signer_sk: str, request_ev: EventLike, content: str, now: int, amount_msat: int = 0,
commit: str = '', extra_tags: Optional[Sequence[Sequence[str]]] = None) -> NostrEvent:
"""Kind request+1000: tags e, p, request, then amount / commit / extras."""
k = request_ev.get('kind', 5000)
tags: list[list[str]] = [['e', str(request_ev.get('id', ''))], ['p', str(request_ev.get('pubkey', ''))],
['request', crypto.canonical(request_ev).decode()]]
if amount_msat > 0:
tags.append(['amount', str(int(amount_msat))])
if commit:
tags.append(['commit', commit])
for xt in extra_tags or []:
if xt:
tags.append([str(x) for x in xt])
return store.make_signed_event(signer_sk, now, result_kind(k if isinstance(k, int) else 5000), tags, content)