feat: harden asset management with critical trustline fix and mainnet…

[murat48]

Summary

This PR adds assetManagementTool to the Stellar AgentKit, enabling developers to manage Stellar assets programmatically — including balance queries, trustline management, and custom asset issuance. The implementation includes production-grade security from the start, with mainnet safeguards and strict input validation consistent with the project's "safe by default" philosophy.

What's Added

tools/assetManagement.ts

A new DynamicStructuredTool with three actions:

• get_balances — Fetch all asset balances (XLM + custom tokens) for the configured account
• manage_trustline — Add or remove trustlines for custom Stellar assets
• create_asset — Issue a new custom asset to a recipient account

Security Features

• Mainnet safeguard: All mainnet operations require ALLOW_MAINNET_ASSET_MANAGEMENT=true in .env, consistent with bridgeTokenTool
• Keypair consistency check: STELLAR_PUBLIC_KEY is verified against STELLAR_PRIVATE_KEY at module load — fails fast with a clear error if mismatched
• Trustline authorization fix: create_asset validates that the recipient already has a trustline before issuing, rather than attempting to sign the recipient's changeTrust with the issuer's keypair (which would violate Stellar's auth model and fail with tx_bad_auth)
• Strict input validation:
  • assetCode: 1–12 alphanumeric characters (regex)
  • assetIssuer / recipientAddress: valid Ed25519 public keys via StrKey
  • amount / limit: positive numbers, max 7 decimal places (Stellar precision limit)

Documentation

• Added 💰 Asset Management section to README.md with usage examples, mainnet instructions, and error scenarios
• Added ALLOW_MAINNET_ASSET_MANAGEMENT to .env and .env.example

Integration

• Exported via index.ts as part of stellarTools array — immediately available to all AgentKit consumers

Testing

pnpm build
✅ No TypeScript errors

node [test-asset-tool-with-create-asset.mjs]
✅ get_balances — PASS
✅ manage_trustline — PASS
✅ create_asset — PASS

Backward Compatibility

• ✅ Testnet: no impact on existing functionality

---

Summary by cubic

Adds a secure asset_management tool with balances, trustline management, and custom asset issuance, plus a critical trustline authorization fix. Also introduces mainnet safeguards, unified transaction building, and docs/tests to make asset operations safe and predictable.

• New Features

  • asset_management actions: get_balances, manage_trustline, create_asset.
  • Exported via stellarTools; adds AgentClient and network-aware bridge helper.
  • Unified builders: buildTransaction and buildTransactionFromXDR used by LP, stake, and bridge flows.
  • Docs, examples, and tests added; simple wallet generator (createwallet/create_wallet.mjs).

• Bug Fixes / Hardening

  • Fixed asset issuance flow: no signing recipient trustlines; requires recipient trustline first.
  • Mainnet safeguards: require ALLOW_MAINNET_ASSET_MANAGEMENT=true and ALLOW_MAINNET_BRIDGE=true to run on mainnet.
  • Strict validation: asset code regex, Ed25519 checks via StrKey, amounts with up to 7 decimals, keypair consistency check at load.
  • Bridge improvements: better restore handling, structured status responses, and correct network passphrase for XDR.

^{Written for commit e5afaf6. Summary will update on new commits.}

[gitguardian]

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

Since your pull request originates from a forked repository, GitGuardian is not able to associate the secrets uncovered with secret incidents on your GitGuardian dashboard.
Skipping this check run and merging your pull request will create secret incidents on your GitGuardian dashboard.

🔎 Detected hardcoded secret in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
-	-	Generic High Entropy Secret	e5afaf6	.env	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secret safely. Learn here the best practices.
3. Revoke and rotate this secret.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[cubic-dev-ai]

1 issue found across 23 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tools/assetManagement.ts">

<violation number="1" location="tools/assetManagement.ts:17">
P2: Module-level Stellar key validation throws on import, so importing the toolkit will crash if STELLAR_PUBLIC_KEY/PRIVATE_KEY aren’t set even when asset management isn’t used. Defer validation until the tool is invoked or lazily initialize to avoid breaking initialization.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}