105 lines
2.5 KiB
Markdown
105 lines
2.5 KiB
Markdown
# amduat-api
|
|
|
|
`amduat-api` builds `amduatd`, a minimal HTTP server over a Unix domain socket that exposes Amduat substrate operations for a **single ASL store root**.
|
|
|
|
## Build
|
|
|
|
```sh
|
|
cmake -S . -B build
|
|
cmake --build build -j
|
|
```
|
|
|
|
## Core dependency
|
|
|
|
This repo vendors the core implementation as a git submodule at `vendor/amduat`.
|
|
|
|
```sh
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
## Quickstart (local)
|
|
|
|
Initialize a store:
|
|
|
|
```sh
|
|
./vendor/amduat/build/amduat-asl init --root .amduat-asl
|
|
```
|
|
|
|
Run the daemon:
|
|
|
|
```sh
|
|
./build/amduatd --root .amduat-asl --sock amduatd.sock
|
|
```
|
|
|
|
Dev loop (build + restart):
|
|
|
|
```sh
|
|
./scripts/dev-restart.sh
|
|
```
|
|
|
|
Query store meta:
|
|
|
|
```sh
|
|
curl --unix-socket amduatd.sock http://localhost/v1/meta
|
|
```
|
|
|
|
Discover the store-backed API contract ref:
|
|
|
|
```sh
|
|
curl --unix-socket amduatd.sock 'http://localhost/v1/contract?format=ref'
|
|
```
|
|
|
|
Fetch the contract bytes (JSON):
|
|
|
|
```sh
|
|
curl --unix-socket amduatd.sock http://localhost/v1/contract
|
|
```
|
|
|
|
Upload raw bytes:
|
|
|
|
```sh
|
|
curl --unix-socket amduatd.sock -X POST http://localhost/v1/artifacts \
|
|
-H 'Content-Type: application/octet-stream' \
|
|
--data-binary 'hello'
|
|
```
|
|
|
|
Download raw bytes:
|
|
|
|
```sh
|
|
curl --unix-socket amduatd.sock http://localhost/v1/artifacts/<ref>
|
|
```
|
|
|
|
Download artifact framing (`ENC/ASL1-CORE v1`):
|
|
|
|
```sh
|
|
curl --unix-socket amduatd.sock \
|
|
'http://localhost/v1/artifacts/<ref>?format=artifact' --output artifact.bin
|
|
```
|
|
|
|
Run a PEL program from store-backed refs (default `scheme_ref=dag`):
|
|
|
|
```sh
|
|
curl --unix-socket amduatd.sock -X POST http://localhost/v1/pel/run \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"program_ref":"<program_ref>","input_refs":["<input_ref_0>"],"params_ref":"<params_ref>"}'
|
|
```
|
|
|
|
## Current endpoints
|
|
|
|
- `GET /v1/meta` → `{store_id, encoding_profile_id, hash_id, api_contract_ref}`
|
|
- `GET /v1/contract` → contract bytes (JSON) (+ `X-Amduat-Contract-Ref` header)
|
|
- `GET /v1/contract?format=ref` → `{ref}`
|
|
- `POST /v1/artifacts`
|
|
- raw bytes: `Content-Type: application/octet-stream` (+ optional `X-Amduat-Type-Tag: 0x...`)
|
|
- artifact framing: `Content-Type: application/vnd.amduat.asl.artifact+v1`
|
|
- `GET|HEAD /v1/artifacts/{ref}`
|
|
- raw bytes default
|
|
- artifact framing: `?format=artifact`
|
|
- `POST /v1/pel/run`
|
|
- request: `{program_ref, input_refs[], params_ref?, scheme_ref?}` (refs are hex strings; omit `scheme_ref` to use `dag`)
|
|
- response: `{result_ref, trace_ref?, output_refs[], status}`
|
|
|
|
## Notes
|
|
|
|
- This is intentionally a local-first surface (Unix socket, no TLS). HTTPS can be added later without changing the semantics.
|