Asentum

Concepts

Secrets and Workers

How smart contracts on Asentum trigger real API calls. Estimated read time: 8 minutes

TL;DR

Asentum lets a smart contract trigger an outbound HTTP call using an API key stored on chain in encrypted form. The schedule, the authorization, and the audit trail are enforced by smart contract code. The actual decryption and the call happen in an off-chain Worker process that the chain authenticates by its registered public key.

Two on-chain primitives. The Vault stores encrypted secrets and decides who can ask for them. Workers are off-chain processes that watch the chain for authorized requests, perform the work, and post a signed receipt back. Together with native cron they form a pattern no other blockchain has: an autonomous, scheduled, auditable HTTP executor governed by smart contract code.

The problem

A smart contract that wants to interact with the real world needs to call an API. To call an API, you need a credential. To store the credential, you need somewhere to put it.

Putting it on chain in cleartext is obviously a bad idea. The chain is public. Encrypting it with the contract's own "key" doesn't work either, because the contract's code is also public, so whoever runs a chain node can replay the decryption.

Most chains punt this. Either you trust a centralized oracle to feed data in, or you run an off-chain bot that holds the credential in its env vars and watches the chain for events to act on. Both patterns push the meaningful decisions, when to fire, with what credentials, to do what, off-chain. The blockchain stops being a chain and becomes a billboard for events that the off-chain part of your system mostly ignores.

Architecture

The Asentum answer splits the problem into two pieces. The chain owns the AUTHORIZATION and the AUDIT TRAIL. An off-chain Worker owns the EXECUTION. The two are connected by encrypted ciphertext that only the Worker can read.

         on chain                           off chain
┌──────────────────────────────┐    ┌─────────────────────────┐
│  Vault contract              │    │  Worker daemon          │
│  ┌──────────────────────┐    │    │                         │
│  │ ciphertext           │◄───┤    │  - tails chain          │
│  │ owner                │    │    │  - reads ciphertext     │
│  │ authorized contracts │    │    │  - decrypts in memory   │
│  │ workerId             │    │    │  - validates URL policy │
│  └──────────────────────┘    │    │  - makes HTTP call      │
│                              │    │  - signs fulfillment    │
│  Your contract               │◄───┤  - posts receipt        │
│  └ cron schedule             │    │                         │
│  └ requestDecryption(...)    │    │                         │
│    emits WorkRequested ──────┼───►│                         │
│                              │    │                         │
│  WorkerRegistry              │    │                         │
│  └ hybrid pubkey lookup ─────┼────┘                         │
└──────────────────────────────┘                              │
                                                              │

The Worker has no privileged channel into the chain. It signs its fulfillment tx with the same kind of Dilithium3 keypair every other Asentum account uses. The Vault contract verifies the tx signer matches the workerId registered on the WorkerRegistry. Same machinery, same security guarantees as any other tx.

Cryptography

Secrets are encrypted with a hybrid scheme: X25519 plus ML-KEM-768, with ChaCha20-Poly1305 as the symmetric AEAD. Both KEM outputs are combined via HKDF-SHA256 into the symmetric key.

  • X25519 is the classical leg. Battle-tested, fast, mature library support across every JS runtime.
  • ML-KEM-768 is the NIST post-quantum KEM standard. Asentum is a post-quantum chain on the signing side already, so we extend that into encryption too.
  • ChaCha20-Poly1305 is the symmetric AEAD that does the actual work on the plaintext.

The hybrid choice is belt and braces. If X25519 is broken by a future quantum attacker, ML-KEM still protects the secret. If ML-KEM is broken by classical cryptanalysis (it's a young standard), X25519 still protects. Cost is about 1.2 KB of fixed overhead per ciphertext, fine for env-var-sized data.

See Post-Quantum Cryptography for the broader story.

Authorization model

The owner of a secret declares a closed list of authorized contracts at put time, and can add or remove members later. The Vault's requestDecryption method checks msg.sender against that list and refuses calls from anyone else.

Two more constraints apply per Worker, enforced off-chain by the Worker daemon itself:

  • Host allowlist. Each Worker reads an allowed-hosts.json file at boot that says which destinations it will ever call, and which HTTP verbs against each. A contract that asks the Worker to call something off this list gets refused with a logged error.
  • Policy hash on chain. The Worker commits a sha256 of its policy plus version string to the chain at registration time. Anyone auditing can verify exactly which policy a Worker was running at any block height, even after the operator rotates the file.

The chain enforces who can ASK. The Worker enforces what it will DO. Defense in depth.

What lives on chain

Every interesting event leaves a trail on chain:

  • SecretPut, SecretRotated, SecretDeleted
  • SecretAuthorized, SecretRevoked
  • WorkRequested, WorkFulfilled
  • WorkerRegistered, WorkerKeyRotated, WorkerDeregistered

An indexer or block explorer can render the full lifecycle of any secret: when it was created, who has been authorized against it, every job that has ever fired against it, the response hash for each fulfillment, and the Worker that did the work. Comparable to a Datadog audit log, except impossible to retroactively edit.

Trust assumptions

The honest list:

  • You trust the Worker operator with reading the plaintext of any secret encrypted to that Worker. There is no way around this on a transparent chain.
  • You trust the Worker to report the response honestly. The fulfillment tx contains the response hash, but the response body itself lives in the Worker's memory. A malicious Worker could fabricate a response. Mitigation: contracts that care about response integrity can run two Workers and require matching hashes.
  • You do not trust other contracts to trigger your secret. The authorization list is the gate.
  • You do not trust validators to read your secret. Validator nodes store the ciphertext but never see the plaintext.

For the early phase, Asentum hosts a default Worker that anyone can target for free. Operators who want to eliminate the trust-the-host concern can run their own Worker in 5 minutes with npm install @asentum/workers.

Where this is going

Three things on the roadmap to tighten the trust model further:

  • Threshold decryption. The secret is encrypted such that decryption requires t-of-n Workers to cooperate. Single-Worker trust becomes a quorum-of-Workers trust.
  • Trusted Execution Environments. Run the Worker inside Intel SGX or AMD SEV. The host operator can no longer read the plaintext even with physical access. Reserved for high-stakes credentials where the existing model is insufficient.
  • Response integrity oracles. Multiple Workers fulfill the same job. The contract only accepts the result if a quorum agrees on the response hash. Mitigates the "malicious Worker forges a response" case.

The current model is enough for the bulk of real applications. The roadmap items are upgrades for specific threat models, not blockers for general use.

Ready to build something? Head over to the Secrets and Workers developer guide.