Functions

A function is the unit of deployment, execution and earnings: one owner, one slug, an immutable version history, and a public endpoint at /api/cloud/v1/fn/{owner}/{slug}.

Configuration

field	meaning
`slug`	URL identity, unique per owner, immutable after creation
`entrypoint`	module-level callable name (default `main`)
`timeoutMs / memoryMb`	execution envelope, clamped server-side to the platform ceilings (300s / 1024 MB)
`capabilities`	what the function may ask the host to do — see capabilities
`perCallNanm`	your per-call surcharge in integer nANM, added on top of metered cost on successful runs
`visibility`	`PUBLIC` (marketplace-listed; needs the publishing entitlement) · `UNLISTED` (reachable by URL) · `PRIVATE` (owner only)
`requiresAuth`	force API-key auth even for a free public function

Deployment lifecycle

Every deployment is tracked through a persisted lifecycle, with a full log at each step:

CloudDeployment.status

DRAFT → VALIDATING → BUILDING → AWAITING_SIGNATURE → BROADCASTING → CONFIRMING → ACTIVE
                                                                                  ↘ FAILED

VALIDATING — AST-only static validation (never executes your code): syntax, entrypoint signature, import policy, dangerous-call patterns, secret-shaped literals (warning). Fails closed: a broken validator is a retryable 503, never a silent pass.
BUILDING — the canonical artifact manifest is computed (sourceSha3 = SHA3-256 of the verbatim source; artifactSha3 = SHA3-256 of a sorted-key manifest binding source hash, entrypoint, package set and runtime) and the full bundle (manifest + verbatim source) is stored in the Animica DA layer, content-addressed — the blob id is the SHA3-256 of the bytes.
AWAITING_SIGNATURE → BROADCASTING — the platform's anchor wallet signs an on-chain DEPLOY (t=1) transaction whose manifest binds {owner, function, version, sourceSha3, artifactSha3, daBlobId}.
CONFIRMING — bounded wait for inclusion; the recorded confirmation depth keeps updating in the background until finality (12 confirmations).
ACTIVE — the endpoint serves the new version.

Anchoring honesty: deployments are anchored on-chain and executed off-chain in a hardened container — Animica consensus does not execute arbitrary Python (vm_py CALL txs revert on mainnet by design). If an anchor cannot be broadcast (say, the anchor wallet cannot pay gas), the deployment still activates and is recorded as unanchored with the real reason — the platform never fabricates a txid. Deploying costs the developer 0 nANM; the platform pays the anchor gas.

Versions, redeploys, rollbacks

Version history is append-only. A version row snapshots the verbatim source, its hashes, the validation report and the deploy-time cost estimate; it is never modified afterwards. A redeploy creates version max+1; a rollback creates a new deployment pointing at an old version row.

version operations

# push new source  -> immutable version max+1, deployed
POST /api/cloud/v1/functions/{id}/versions   { "source": "…", "entrypoint": "main", "packages": [] }

# redeploy an existing version (no new snapshot), or resume a stalled attempt
POST /api/cloud/v1/functions/{id}/deploy     { "version": 3 } | { "deploymentId": "…" }

# roll back = a NEW deployment pointing at an OLD version (history is never rewritten)
POST /api/cloud/v1/functions/{id}/rollback   { "version": 2 }

The public endpoint

GET (query params → request) and POST (JSON body → request), CORS-open for public functions.
{owner} is your handle, or your anim1… address before a handle is claimed.
Response headers on every call: x-animica-request-id, x-animica-cost-nanm, x-animica-status.
Anonymous callers reach only public, auth-optional, zero-surcharge functions, inside the free tier; everything else needs an API key.
Failures are billed events (metered resources only, no surcharge) and return the real error:

error response (HTTP 500 / 504)

// failed executions return the developer's real error, plus what the run cost:
{
  "error": { "code": "function_error", "message": "…", "type": "ValueError" },
  "requestId": "rq_…",
  "cost": { "nanm": "2934181", "asset": "ANM" }
}

Operational endpoints

Owner-side management lives under /api/cloud/v1/functions: list/create, detail/update/archive, version history, deployment history, per-execution history with exact money, and secret-redacted logs. See the REST API reference.

Secrets

Store per-function or account-wide secrets via POST /api/cloud/v1/secrets. Values are sealed with AES-256-GCM before they touch the database, injected into executions as animica.secret("NAME"), redacted from stored logs, and never returned by any API after creation.

← Supported packages Apps →