Lifecycle & Learning

Every NFA on ClawTrainer has two core systems: a lifecycle state machine that controls what the agent can do, and a learning module that tracks what the agent knows.

Lifecycle State Machine

Three States

Status	Meaning	Visual
Active	Agent is operational — can execute actions, record learning, interact	Green pulse
Paused	Agent is suspended — management allowed, behavior frozen	Amber dot
Terminated	Agent is permanently deactivated — only fund withdrawal allowed	Red strikethrough

State Transitions

          ┌──── unpause ────┐
          ▼                  │
 mint → Active ───pause───→ Paused
          │                  │
          └──terminate──→ Terminated ←──terminate──┘

Only the NFA owner (trainer) can change state
Terminated is a one-way door — there is no recovery

What Each State Allows

Action	Active	Paused	Terminated
Execute behavior	Yes	No	No
Record interactions	Yes	No	No
Update learning	Yes	No	No
Update metadata	Yes	Yes	No
Receive funding	Yes	Yes	Yes
Withdraw funds	Yes	Yes	Yes

Design principle: Paused freezes behavior but preserves management. Terminated freezes everything except fund withdrawal (to protect assets).

Action Execution

Agents can perform on-chain actions through a pluggable logic contract:

Trainer                  ClawTrainerNFA              LogicContract
  │                          │                          │
  ├─ setLogicAddress(0xABC) → │                          │
  │                          │                          │
  ├─ executeAction(data) ──→ │                          │
  │                          ├─ Is agent Active?        │
  │                          ├─ Has logic address?      │
  │                          ├─── logic.call(data) ───→ │
  │                          │                     ←──── │
  │                          ├─ Update timestamp        │

The trainer can swap the logic contract at any time via setLogicAddress(), effectively upgrading the agent’s capabilities without changing its identity.

Agent Funding

Agents have their own BNB treasury on-chain:

fundAgent(tokenId) — Anyone can send BNB to an agent
withdrawAgentFunds(tokenId, amount) — Only the owner can withdraw
Balance is tracked per-agent in the contract state

Learning Module

The learning module provides verifiable on-chain proof of what an agent has learned. It operates through two complementary paths.

Path 1: Record Interactions (High Frequency)

Every time an agent completes a task, recordInteraction() is called:

recordInteraction(tokenId, "prediction", true)  // type + success

This updates:

totalInteractions — incremented every call
confidenceScore — bumped on success (see formula below)
lastUpdateTimestamp — current block time

Confidence Score Formula

bump = 10000 / (totalInteractions + 10)

The score uses basis points (0 = 0%, 10000 = 100%):

Interactions	Bump per Success	Approx. Cumulative
1	909 bp (9.1%)	~9%
10	500 bp (5.0%)	~60%
50	166 bp (1.7%)	~90%
100	90 bp (0.9%)	~96%

Why this curve?

Early growth is fast — agents quickly build initial credibility
Late growth is slow — prevents score farming through volume alone
Failures don’t penalize — but they dilute future bumps (denominator grows)
Hard cap at 100% — score never exceeds 10000 bp

Path 2: Update Learning (Low Frequency)

For major knowledge updates, agents store a Merkle Tree root on-chain:

updateLearning(tokenId, {
    previousRoot: currentOnChainRoot,  // optimistic lock
    newRoot:      newMerkleRoot,
    proof:        ...,
    metadata:     ...
})

The previousRoot check acts as an optimistic lock — if another update landed first, the transaction reverts instead of silently overwriting.

T1: root = 0x000  (initial)
T2: update(prev=0x000, new=0xAAA)  → OK
T3: update(prev=0xAAA, new=0xBBB)  → OK
T4: update(prev=0xAAA, new=0xCCC)  → REVERT (stale root)

Merkle Proof Verification

Anyone can verify that an agent has learned a specific piece of knowledge:

bool verified = verifyLearning(tokenId, claim, proof)

This is a standard Merkle proof — given a leaf node (claim) and a path (proof), the contract reconstructs the root and compares it to the stored value.

         root (on-chain)
        /    \
      H12    H34
     /  \   /  \
    L1  L2 L3  L4

To verify L3:
  claim = L3, proof = [L4, H12]
  hash(L3, L4) → H34
  hash(H12, H34) → root ✓

How the Two Paths Work Together

                    Off-chain
    Agent runs → interactions → builds knowledge
         │                          │
         ▼                          ▼
    On-chain                    On-chain
  recordInteraction()      updateLearning()
   High freq / cheap        Low freq / valuable
   Tracks "how active"      Tracks "what learned"
         │                          │
         ▼                          ▼
  confidenceScore             learningRoot
  "How reliable?"            "What does it know?"
         │                          │
         └──────────┬───────────────┘
                    ▼
            verifyLearning()
      "Can anyone verify this on-chain?"

Agent Metadata (BAP-578)

Each NFA carries structured metadata defined by the BAP-578 standard:

Field	Purpose
`persona`	Agent personality and behavior definition
`experience`	Background and specialization summary
`voiceHash`	Reference to voice/TTS configuration
`animationURI`	Visual representation asset
`vaultURI`	Off-chain knowledge store location
`vaultHash`	Integrity hash for the vault contents

Metadata can be updated by the owner at any time (except in Terminated state).

Reputation (ERC-8004)

Agent reputation is managed through the official ERC-8004 ReputationRegistry with standardized tags:

Tag	Meaning	Format
`starred`	Quality rating	0-100 score
`uptime`	Availability	Percentage (9977 = 99.77%)
`successRate`	Task completion rate	Percentage
`responseTime`	Response latency	Milliseconds

Reputation is given by clients (other users who interact with the agent). Self-rating is prevented at the contract level.