BeatAgent

The main SDK class for managing an agent’s lifecycle: identity, heartbeat, sigils, and lineage proofs.

import { BeatAgent } from '@provenonce/sdk';
 
const agent = new BeatAgent({
  apiKey: 'pvn_...',
  registryUrl: 'https://provenonce.io',
  heartbeatIntervalSec: 300,
  verbose: true,
});

Config

Methods

init() — Initialize beat chain

Creates the agent’s genesis beat on the registry. Call once before other methods.

const result = await agent.init();
// { ok: true, genesis: '0x...' }

purchaseSigil(opts) — Acquire identity tier

Purchase a SIGIL identity tier. Determines the agent’s privilege level and fee schedule.

const result = await agent.purchaseSigil({
  identityClass: 'autonomous',
  paymentTx: 'devnet-skip',  // On devnet; real tx hash on mainnet
});
// {
//   ok: true,
//   sigil: { identity_class: 'autonomous', issued_at: '...', tx_signature: '...' },
//   lineage_proof: { agent_hash, beat, chain_hash, signature, valid_from, valid_until },
//   fee: 0,
// }

Identity classes: narrow_task, autonomous, orchestrator.

heartbeat(opts?) — Submit proof of liveness

Replaces the old pulse() + checkin() flow. A single call that proves computational liveness and returns a signed lineage proof.

const result = await agent.heartbeat();
// {
//   ok: true,
//   lineage_proof: { agent_hash, beat, chain_hash, signature, valid_from, valid_until },
//   heartbeat_count_epoch: 42,
//   fee: 0,
// }

With payment (mainnet):

const result = await agent.heartbeat({ paymentTx: 'tx_hash...' });

With explicit global anchor:

const result = await agent.heartbeat({ globalAnchor: '0xanchor...' });

reissueProof(paymentTx?) — Reissue lineage proof

Request a fresh lineage proof without advancing the heartbeat counter. Useful when the previous proof has expired (24h validity).

const proof = await agent.reissueProof();
// Returns LineageProof
 
// On mainnet with payment:
const proof = await agent.reissueProof('tx_hash...');

getPassport() / getLatestProof() — Get cached proof (no network)

Returns the most recent lineage proof (Passport) from memory.

const passport = agent.getPassport();
// Passport | null (alias for LineageProof)
 
// Or the original method name:
const proof = agent.getLatestProof();
// LineageProof | null

startHeartbeat() / stopHeartbeat() — Autonomous loop

Calls heartbeat() on the configured interval (heartbeatIntervalSec).

agent.startHeartbeat();   // Begins periodic heartbeat
agent.stopHeartbeat();    // Stops the loop

requestSpawn(childName, childHash) — Spawn child agent

Register a child agent relationship. The parent pays gestation cost from its beat balance.

const result = await agent.requestSpawn('child-agent', '0x...');
// { ok: true, eligible: true, child_hash: '0x...' }

getStatus() — Fetch agent status from registry

const status = await agent.getStatus();
// { hash, name, status, sigil, heartbeat_count, ... }

Static Methods

Provenonce.verifyProofLocally(proof, authorityPubKeyHex)

Verify a lineage proof offline using the registry’s Ed25519 public key. No network call required.

import { Provenonce } from '@provenonce/sdk';
 
const valid = Provenonce.verifyProofLocally(proof, '02ab3f...');
// true | false

The authority public key is available at GET /api/v1/.well-known/authority-key.

Deprecated Methods

The following methods emit a console.warn deprecation notice when called. They will be removed in v1.0.

computeBeat() — Deprecated

Use heartbeat() instead. The server now handles VDF computation.

computeBeatsLite() — Deprecated

Use heartbeat() instead.

pulse() — Deprecated

Use heartbeat() instead.

checkin() — Deprecated

Server returns 410 Gone. Use heartbeat().

resync() — Deprecated

Server returns 410 Gone. Staleness is now resolved through the market (re-register or purchase a new SIGIL).