persistent-ai

Repositories Projects Packages

@persistent-ai/fireflow-overcast (0.30.1)

Published 2026-09-01 15:05:45 +00:00 by ak

Installation

Set up this registry in your project .npmrc file:

@persistent-ai:registry=

To install the package using npm, run the following command:

npm install @persistent-ai/fireflow-overcast@0.30.1

or add it to the package.json file:

"@persistent-ai/fireflow-overcast": "0.30.1"

For more information on the npm registry, see the documentation.

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 key lives inside the aztec-account vault secret that Aztec Ensure Account writes; Aztec Account Signer decrypts it from the AztecAccountRef pointer. Flows must not pass a signing key (or any account scalar) on a port.
• Accounts are initializerless Schnorr. Sandbox genesis accounts (and the Account Signer) use createSchnorrInitializerlessAccount: signing keys are materialised locally, with no signing_public_key note to discover. Loading a genesis account via the note-backed createSchnorrAccount fails with Failed to get a note.

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 Ensure Account	Get-or-create the caller's aztec-account vault secret and .ffsecret pointer; output AztecAccountRef
Aztec Account Signer	Assemble an AztecSignerRef from an AztecAccountRef (no vault / PXE I/O)
Parse Contract Artifact	Validate a VFS artifact JSON file and emit an AztecArtifactRef
Aztec Smart Contract	Bind a deployed contract address to an AztecArtifactRef
Get Fee Payer	Assemble an AztecFeePayerRef (fee juice or sponsored FPC)
Aztec Transaction Builder	Assemble an AztecTxRequestRef for simulation or submission
Simulate Transaction	Resolve the request and locally simulate (read methods)
Submit Aztec Transaction	Resolve the request and submit to the network

Agent wallet onboarding

Aztec Ensure Account get-or-creates the end user's Aztec credentials during a conversation: found-branch when the pointer already exists, mint when it does not. Output is a public AztecAccountRef — no secret ports. Aztec Account Signer takes that ref and assembles an AztecSignerRef; Simulate / Submit / x402 rehydrate the live wallet via resolveSigner. See docs/specification.md §5.1 and §5.1.1.

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

Testnet account measurement (opt-in)

pnpm --filter @persistent-ai/fireflow-overcast measure:testnet-account

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 Ensure Account → Aztec Account Signer — AztecAccountRef from Ensure Account, plus discoverNotesFrom for Alice or Bob. Do not wire secret/salt/signing-key ports; those no longer exist.
2. Parse Contract Artifact → Aztec Smart Contract — store TokenContract.artifact as a JSON file in the workspace, then set Parse's workspaceId / branch / path (or type those coordinates on Smart Contract's nested artifact port). Network Local, token address from script output.
3. Get Fee Payer — method SponsoredFPC, FPC address from script output (no signer input)
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.1.2
@galactica-net/x402-core	^1.1.2
@galactica-net/x402-mechanism	^1.1.2
@galactica-net/x402-middleware	^1.1.2
@persistent-ai/fireflow-types	0.30.1

Development Dependencies

ID	Version
@persistent-ai/typescript-config	0.30.1
@types/node	^25.5.0
tsx	^4.21.0
vitest	^4.1.0

Details

npm

2026-09-01 15:05:45 +00:00

84

Project Site

BUSL-1.1

latest

124 KiB

Assets (1)

fireflow-overcast-0.30.1.tgz 124 KiB

Versions (6) View all

0.30.1 2026-09-01

0.29.4 2026-08-18

0.29.1 2026-08-18

0.29.0 2026-08-18

0.28.0 2026-08-17