persistent-ai
Repositories Projects Packages

@persistent-ai/fireflow-overcast (0.28.0)

Published 2026-08-17 13:00:39 +00:00 by ak

Installation

@persistent-ai:registry=
npm install @persistent-ai/fireflow-overcast@0.28.0
"@persistent-ai/fireflow-overcast": "0.28.0"

About this package

@persistent-ai/fireflow-overcast

FireFlow nodes for Overcast — private stablecoin payments on the Aztec blockchain.

Overview

This package provides atomic FireFlow graph nodes that let an AI agent execute private stablecoin payments using the Overcast protocol on Aztec. Each node is a single operation with defined inputs and outputs, composable into larger payment flows.

See docs/specification.md for the full node roadmap.

Aztec version

Pinned to @aztec/* 5.0.1 (was 4.2.0), matching the version the public testnet and mainnet run. The AIP-20 token comes from @aztec-foundation/aztec-standards@5.0.1, whose own config.aztecVersion is 5.0.1 — SDK and artifact are built against the same release.

aztec-standards moved to AztecProtocol and now publishes under the @aztec-foundation scope. The old @defi-wonderland scope has no stable v5.

Two consequences worth knowing before using this package:

  • Every account address changes, and old accounts are unusable. v5 reworked the key hierarchy (PublicKeys now exposes poseidon2 hashes), added immutablesHash to address derivation, and switched Schnorr from blake2s/pedersen to Poseidon2. A Schnorr account deployed under v4 cannot be controlled by v5 code — accounts must be redeployed.
  • The signing key is now required. It is the root of the key hierarchy, so it can no longer be derived from the account secret (deriveSigningKey was removed). The Aztec Account Signer node's Signing Key port changed from optional to required; flows that relied on derivation must supply one explicitly.

The token's constructor_with_minter takes an auth_contract argument. Pass AztecAddress.ZERO to disable it. It is the token's own authorization hook, not the standard auth registry — passing the registry address makes every transfer revert.

Nodes (current iteration)

Node Description
Aztec Account Signer Load account from secret/salt, initialize PXE, register senders for note discovery
Aztec Smart Contract Bind a deployed contract address to its artifact
Get Fee Payer Configure fee payment (native fee juice or sponsored FPC)
Aztec Transaction Builder Build a contract method call for simulation or submission
Simulate Transaction Locally simulate a prepared transaction (read methods)
Submit Aztec Transaction Submit a prepared transaction to the network

Environment

Variable Default Description
AZTEC_NODE_URL http://localhost:8080 Aztec node RPC endpoint

Development

pnpm --filter @persistent-ai/fireflow-overcast build
pnpm --filter @persistent-ai/fireflow-overcast test
pnpm --filter @persistent-ai/fireflow-overcast typecheck

Integration tests

Requires a local Aztec sandbox running at http://localhost:8080:

pnpm --filter @persistent-ai/fireflow-overcast test:integration

Manual UI testing

Deploy local Aztec fixtures (accounts, Sponsored FPC, Token contract, Alice mint) and print copy-paste values for wiring Overcast nodes in the FireFlow editor.

Prerequisite: local Aztec sandbox at http://localhost:8080 (same as integration tests).

pnpm --filter @persistent-ai/fireflow-overcast deploy:local

After deployment, check Alice and Bob private balances anytime:

pnpm --filter @persistent-ai/fireflow-overcast balances:local <address-from-deploy-output>

Alternatively, pass the token address via environment variable:

TOKEN_CONTRACT_ADDRESS=<address-from-deploy-output> \
  pnpm --filter @persistent-ai/fireflow-overcast balances:local

Optional environment overrides:

Variable Default Description
MINT_AMOUNT 1000 Private tokens minted to Alice
TOKEN_CONTRACT_ADDRESS (CLI arg preferred) Token contract from deploy:local output (fallback if no CLI arg)

Wire flows using the printed values and docs/specification.md:

  1. Aztec Account Signer — secret, salt, signing key (secret ports), and discoverNotesFrom for Alice or Bob
  2. Parse Contract Artifact → Aztec Smart Contract — token address, network Local, artifact from the @aztec-foundation/aztec-standards Token contract
  3. Get Fee Payer — method SponsoredFPC, FPC address from script output
  4. Aztec Transaction Builder / Simulate Transaction / Submit Aztec Transaction — e.g. balance_of_private or transfer_private_to_private

Suggested test flow: read Alice balance → transfer to Bob → read both balances.

Exports

  • @persistent-ai/fireflow-overcast — client-safe shared types
  • @persistent-ai/fireflow-overcast/nodes — node registration (frontend)
  • @persistent-ai/fireflow-overcast/server — server barrel (executor / worker)

Dependencies

Dependencies

ID Version
@aztec-foundation/aztec-standards 5.0.1
@aztec/accounts 5.0.1
@aztec/aztec.js 5.0.1
@aztec/constants 5.0.1
@aztec/noir-contracts.js 5.0.1
@aztec/stdlib 5.0.1
@aztec/wallet-sdk 5.0.1
@aztec/wallets 5.0.1
@galactica-net/x402-client ^1.0.0
@galactica-net/x402-core ^1.0.0
@galactica-net/x402-mechanism ^1.0.0
@galactica-net/x402-middleware ^1.0.0
@persistent-ai/fireflow-types 0.28.0

Development Dependencies

ID Version
@persistent-ai/typescript-config 0.28.0
@types/node ^25.5.0
tsx ^4.21.0
vitest ^4.1.0
Details
npm
2026-08-17 13:00:39 +00:00
1
Project Site
BUSL-1.1
86 KiB
Assets (1)
fireflow-overcast-0.28.0.tgz 86 KiB
Versions (5) View all
0.29.4 2026-08-18
0.29.1 2026-08-18
0.29.0 2026-08-18
0.28.0 2026-08-17
0.26.2 2026-08-10