docs: run the agent-wallet lifecycle from JavaScript

[MicBun]

resolves: https://github.com/truflation/website/issues/4165

Problem

There's no runnable, end-to-end example showing the full Modular Agent Address ("agent wallet") lifecycle through the JS SDK. The Go and Python SDKs each have one, but JS developers have nothing to copy from.

Change

Adds examples/maa_lifecycle_example/ — a self-contained smoke test mirroring the Go/Python examples and the node oracle (tests/streams/maa/data_agent_test.go). It drives the whole lifecycle against a live node where maa_exec is activated and asserts the properties that make an agent wallet safe:

• a restricted agent key registers an immutable rule; an unrestricted owner key joins it to derive + fund the wallet (the MAA);
• the agent runs allow-listed actions as the MAA — @caller is rewritten to the wallet, so the stream it creates is owned by the MAA and every fee debits the MAA's own escrow;
• the agent cannot withdraw (owner-exit actions are reserved for the owner);
• the owner withdraws the remaining escrow, paying the agent its commission;
• positions/collateral are read by address (migration 051).

rule_id and the MAA address are derived offline (MAAAddress.*) and cross-checked against what the chain returns at each step. Config is read from a gitignored .env (template in .env.example); README documents every step and what success looks like.

Verification

Ran end-to-end against testnet — all steps pass, ending with ✅ MAA lifecycle smoke test PASSED. The agent's withdrawal is blocked with reserved for the unrestricted owner and the escrow is unchanged; the owner's withdrawal succeeds with a 2.5% commission.

Depends on

The example calls the address-parameterized getters added here; merge that first (this PR is stacked on its branch):

• feat: read any wallet's order-book portfolio by address #162

[holdex]

Time Submission Status

Member	#	Time	Running Total	Status	Last Update
MicBun			3h	✅ Submitted	Jun 24, 2026, 2:47 PM

---

Submit or update total time with:

@holdex pr submit-time 2h

Add time on top of previous submission with:

@holdex pr add-time 1h30m

See available commands to help comply with our Guidelines.

[coderabbitai]

Warning

Review limit reached

@MicBun, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 12 minutes and 6 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 563ebd9c-8305-4d04-bb49-f146e8f89532

📥 Commits

Reviewing files that changed from the base of the PR and between 74f0b78 and 6aaaffa.

📒 Files selected for processing (4)

• examples/maa_lifecycle_example/.env.example
• examples/maa_lifecycle_example/README.md
• examples/maa_lifecycle_example/main.ts
• examples/maa_lifecycle_example/package.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/maa-lifecycle-example-js

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[MicBun]

@holdex pr submit-time 3h