AGENT SKILL

assets

Stellar Assets (classic) + trustlines + Stellar Asset Contract (SAC) bridge to Soroban. Covers asset issuance, distribution, authorization flags, clawback, regulated assets, trustline management, and the SAC interop layer that exposes classic assets as Soroban tokens. Use when tokenizing real-world assets, issuing stablecoins, managing trustlines, or bridging classic assets to Soroban contracts.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 6
Forks
3

01 前言 Front Matter

name
assets
metadata
{ "argument-hint": "[asset task]", "user-invocable": "true" }
description
Stellar Assets (classic) + trustlines + Stellar Asset Contract (SAC) bridge to Soroban. Covers asset issuance, distribution, authorization flags, clawback, regulated assets, trustline management, and the SAC interop layer that exposes classic assets as Soroban tokens. Use when tokenizing real-world assets, issuing stablecoins, managing trustlines, or bridging classic assets to Soroban contracts.

03 SKILL.md 正文

Stellar Assets, Trustlines, and SAC

Stellar's native token mechanism: classic asset issuance, trustlines, and the Stellar Asset Contract (SAC) bridge that makes classic assets usable from Soroban. Default to classic assets over custom Soroban tokens unless you need custom logic.

When to use this skill

  • Issuing a new asset (stablecoin, security token, utility token)
  • Setting up trustlines from a client or contract
  • Managing issuer flags (auth required, auth revocable, clawback)
  • Bridging a classic asset into a Soroban contract via SAC
  • Building regulated-asset flows (compliance, KYC, freeze)

Related skills

  • Custom token contracts (when classic isn't enough) → ../soroban/SKILL.md
  • UI flows for trustline creation and asset display → ../dapp/SKILL.md
  • Looking up balances and trustline state → ../data/SKILL.md
  • Token-related SEPs (SEP-41, SEP-7, etc.) → ../standards/SKILL.md

Overview

Stellar has two token mechanisms:

  1. Stellar Assets (Classic): Built-in, highly efficient, full ecosystem support
  2. Soroban Tokens: Custom contracts with flexible logic

Recommendation: Prefer Stellar Assets unless you need custom token logic.

Stellar Assets (Classic)

Asset Types

Type Description
Native (XLM) Stellar's native currency, no trustline needed
Credit Issued by an account, requires trustline
Liquidity Pool Shares Represent LP positions

Asset Identifiers

import * as StellarSdk from "@stellar/stellar-sdk";

// Native XLM
const xlm = StellarSdk.Asset.native();

// Credit asset (code + issuer)
const usdc = new StellarSdk.Asset(
  "USDC",
  "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN"
);

// Asset code rules:
// - 1-4 chars: alphanumeric (credit_alphanum4)
// - 5-12 chars: alphanumeric (credit_alphanum12)

Issuing Assets

Create Issuing Account

import * as StellarSdk from "@stellar/stellar-sdk";

const server = new StellarSdk.Horizon.Server("https://horizon-testnet.stellar.org");

// 1. Create issuing account (should be separate from distribution)
const issuerKeypair = StellarSdk.Keypair.random();
const distributorKeypair = StellarSdk.Keypair.random();

// 2. Fund accounts (testnet)
await fetch(`https://friendbot.stellar.org?addr=${issuerKeypair.publicKey()}`);
await fetch(`https://friendbot.stellar.org?addr=${distributorKeypair.publicKey()}`);

Issue Asset

const asset = new StellarSdk.Asset("MYTOKEN", issuerKeypair.publicKey());

// 1. Distributor creates trustline to issuer
const distributorAccount = await server.loadAccount(distributorKeypair.publicKey());

const trustlineTx = new StellarSdk.TransactionBuilder(distributorAccount, {
  fee: StellarSdk.BASE_FEE,
  networkPassphrase: StellarSdk.Networks.TESTNET,
})
  .addOperation(
    StellarSdk.Operation.changeTrust({
      asset: asset,
      limit: "1000000", // Max amount to hold
    })
  )
  .setTimeout(180)
  .build();

trustlineTx.sign(distributorKeypair);
await server.submitTransaction(trustlineTx);

// 2. Issuer sends tokens to distributor
const issuerAccount = await server.loadAccount(issuerKeypair.publicKey());

const issueTx = new StellarSdk.TransactionBuilder(issuerAccount, {
  fee: StellarSdk.BASE_FEE,
  networkPassphrase: StellarSdk.Networks.TESTNET,
})
  .addOperation(
    StellarSdk.Operation.payment({
      destination: distributorKeypair.publicKey(),
      asset: asset,
      amount: "1000000",
    })
  )
  .setTimeout(180)
  .build();

issueTx.sign(issuerKeypair);
await server.submitTransaction(issueTx);

Lock Issuing Account

For fixed-supply tokens, lock the issuer:

const lockTx = new StellarSdk.TransactionBuilder(issuerAccount, {
  fee: StellarSdk.BASE_FEE,
  networkPassphrase: StellarSdk.Networks.TESTNET,
})
  .addOperation(
    StellarSdk.Operation.setOptions({
      masterWeight: 0, // Disable master key
    })
  )
  .setTimeout(180)
  .build();

lockTx.sign(issuerKeypair);
await server.submitTransaction(lockTx);
// Issuer can never issue more tokens

Asset Flags

Configure issuer account flags for compliance:

const setFlagsTx = new StellarSdk.TransactionBuilder(issuerAccount, {
  fee: StellarSdk.BASE_FEE,
  networkPassphrase: StellarSdk.Networks.TESTNET,
})
  .addOperation(
    StellarSdk.Operation.setOptions({
      setFlags:
        StellarSdk.AuthRequiredFlag |    // Trustlines require approval
        StellarSdk.AuthRevocableFlag |   // Can freeze trustlines
        StellarSdk.AuthClawbackEnabledFlag, // Can clawback tokens
    })
  )
  .setTimeout(180)
  .build();

Flag Descriptions

Flag Effect
AUTH_REQUIRED Users must get approval before receiving tokens
AUTH_REVOCABLE Issuer can freeze user balances
AUTH_IMMUTABLE Flags cannot be changed (permanent)
AUTH_CLAWBACK_ENABLED Issuer can clawback tokens from accounts

Authorize Trustline

// When AUTH_REQUIRED is set, approve trustlines:
const authorizeTx = new StellarSdk.TransactionBuilder(issuerAccount, {
  fee: StellarSdk.BASE_FEE,
  networkPassphrase: StellarSdk.Networks.TESTNET,
})
  .addOperation(
    StellarSdk.Operation.setTrustLineFlags({
      trustor: userPublicKey,
      asset: asset,
      flags: {
        authorized: true,
        // authorizedToMaintainLiabilities: true, // Partial auth
      },
    })
  )
  .setTimeout(180)
  .build();

Clawback Tokens

// Requires AUTH_CLAWBACK_ENABLED flag
const clawbackTx = new StellarSdk.TransactionBuilder(issuerAccount, {
  fee: StellarSdk.BASE_FEE,
  networkPassphrase: StellarSdk.Networks.TESTNET,
})
  .addOperation(
    StellarSdk.Operation.clawback({
      asset: asset,
      from: targetAccountId,
      amount: "100",
    })
  )
  .setTimeout(180)
  .build();

Trustlines

Create Trustline

const changeTrustTx = new StellarSdk.TransactionBuilder(userAccount, {
  fee: StellarSdk.BASE_FEE,
  networkPassphrase: StellarSdk.Networks.TESTNET,
})
  .addOperation(
    StellarSdk.Operation.changeTrust({
      asset: asset,
      limit: "10000", // 0 to remove trustline
    })
  )
  .setTimeout(180)
  .build();

Check Trustline Status

const account = await server.loadAccount(userPublicKey);
const trustline = account.balances.find(
  (b) =>
    b.asset_type !== "native" &&
    b.asset_code === "USDC" &&
    b.asset_issuer === usdcIssuer
);

if (trustline) {
  console.log("Balance:", trustline.balance);
  console.log("Limit:", trustline.limit);
  console.log("Authorized:", trustline.is_authorized);
}

Stellar Asset Contract (SAC)

SAC provides Soroban interface for Stellar Assets, enabling smart contract interactions.

Deploy SAC for Existing Asset

# Get the SAC address for an asset
stellar contract asset deploy \
  --asset USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN \
  --source alice \
  --network testnet

SAC Address Derivation

import * as StellarSdk from "@stellar/stellar-sdk";

const asset = new StellarSdk.Asset("USDC", issuerPublicKey);
const contractId = asset.contractId(StellarSdk.Networks.TESTNET);
// Returns the deterministic SAC contract address

Using SAC in Soroban Contracts

use soroban_sdk::{token::Client as TokenClient, Address, Env};

pub fn transfer_asset(
    env: Env,
    from: Address,
    to: Address,
    asset_contract: Address,
    amount: i128,
) {
    from.require_auth();

    // Use standard token interface
    let token = TokenClient::new(&env, &asset_contract);
    token.transfer(&from, &to, &amount);
}

SAC vs Custom Token Interface

SAC implements the standard Soroban token interface:

  • balance(id: Address) -> i128
  • transfer(from: Address, to: Address, amount: i128)
  • approve(from: Address, spender: Address, amount: i128, expiration_ledger: u32)
  • allowance(from: Address, spender: Address) -> i128
  • decimals() -> u32
  • name() -> String
  • symbol() -> Symbol

When to Use What

Use Stellar Assets When:

  • Standard fungible token (currency, stablecoin)
  • Need full ecosystem support (wallets, exchanges)
  • Regulatory compliance features (freeze, clawback)
  • Performance critical (classic operations are cheaper)
  • DEX integration via order book

Use Soroban Custom Tokens When:

  • Complex transfer logic (royalties, fees, restrictions)
  • Custom authorization schemes
  • Non-standard token behaviors
  • Integration with custom DeFi contracts
  • NFTs or semi-fungible tokens

Use SAC When:

  • Need Stellar Asset in Soroban contract
  • Building DeFi protocols with existing assets
  • Bridge between classic and smart contract operations

Querying Assets

Get Account Balances

const account = await server.loadAccount(publicKey);

for (const balance of account.balances) {
  if (balance.asset_type === "native") {
    console.log("XLM:", balance.balance);
  } else {
    console.log(`${balance.asset_code}:`, balance.balance);
  }
}

Find Assets

// Search for assets by code
const assets = await server
  .assets()
  .forCode("USDC")
  .call();

// Get specific asset details
const assetDetails = await server
  .assets()
  .forCode("USDC")
  .forIssuer(issuerPublicKey)
  .call();

Get Asset Statistics

const stats = await server
  .assets()
  .forCode("USDC")
  .forIssuer(issuerPublicKey)
  .call();

// stats includes:
// - amount: total issued
// - num_accounts: trustline count
// - flags: issuer flags

SEP Standards for Assets

SEP-0001 (stellar.toml)

Publish asset metadata in your domain's /.well-known/stellar.toml:

[[CURRENCIES]]
code = "MYTOKEN"
issuer = "GABC..."
display_decimals = 2
name = "My Token"
desc = "A description of my token"
image = "https://example.com/token-logo.png"

SEP-0010 (Web Authentication)

Authenticate users with their Stellar accounts:

// Server generates challenge
// Client signs with wallet
// Server verifies signature

SEP-0024 (Hosted Deposit/Withdrawal)

For fiat on/off ramps:

// Interactive flow for deposits/withdrawals
// Anchor handles KYC and fiat transfer

SEP-0045 (Web Auth for Contract Accounts)

Extends SEP-10 to support Soroban contract accounts (C... addresses) for web authentication. Required for smart wallet / passkey-based anchor integrations. See SEP-0045.

SEP-0050 (Non-Fungible Tokens)

Standard contract interface for NFTs on Soroban. Reference implementations available in OpenZeppelin Stellar Contracts with Base, Consecutive, and Enumerable variants. See SEP-0050.

Best Practices

Asset Issuance

  • Use separate issuing and distribution accounts
  • Lock issuer after initial distribution for fixed supply
  • Publish stellar.toml with asset metadata
  • Consider multisig for issuer account

Trustline Management

  • Check trustline exists before sending payments
  • Handle trustline creation in onboarding flow
  • Respect trustline limits
  • Monitor for frozen/deauthorized status

Security

  • Validate asset issuer, not just code
  • Be cautious of assets with clawback enabled
  • Verify stellar.toml from authoritative source
  • Use well-known asset lists for common tokens

04 同仓库更多 Skills

WritzProtocol
WritzProtocol/writz

zk-proofs

Zero-knowledge proofs and privacy patterns on Stellar. Covers Groth16 verification in smart contracts via BLS12-381 host functions (CAP-0059, available), the BN254 + Poseidon proposals (CAP-0074/0075, status-sensitive), and concrete toolchain walkthroughs for Circom (on-chain verifiable today), Noir, and RISC Zero (attestation pattern until BN254 lands). Use when building privacy-preserving applications, ZK-verifier contracts, or wiring a proving toolchain to Stellar.

★ 6
WritzProtocol
WritzProtocol/writz

tyler-architect

System architect and technical design leader. Use when the user asks to talk to Tyler or requests the architect.

★ 6
WritzProtocol
WritzProtocol/writz

stellar-help

Analyzes current state and user query to answer BMad questions or recommend the next skill(s) to use. Use when user asks for help, bmad help, what to do next, or what to start with in BMad.

★ 6
WritzProtocol
WritzProtocol/writz

stellar-competitive-landscape

Map the competitive landscape for a Stellar project idea. Use when a user says "who are my competitors on Stellar", "competitive analysis Stellar", "what already exists in this space on Stellar", "show me similar Stellar projects", "is anyone else building this on Stellar", or "map the Stellar landscape for X". Queries the 728-project LumenLoop ecosystem database and Electric Capital developer activity to rank competitors by SCF funding history and repo activity.

★ 6
WritzProtocol
WritzProtocol/writz

standards

Stellar standards, ecosystem, and reference. Covers SEPs (Stellar Ecosystem Proposals), CAPs (Core Advancement Proposals), and a quick map for picking the right standard for wallets, anchors, payments, deposits/withdrawals, federation, deep links, and KYC. Also bundles ecosystem references (DeFi protocols, dev tools, wallets, infra, community projects), curated documentation links, and MCP servers (live tools such as Raven). Use when you need to know which SEP applies, or want a starting point for ecosystem integrations, official docs, or live MCP tooling.

★ 6
WritzProtocol
WritzProtocol/writz

smart-contracts

Stellar smart contract development (Rust, soroban-sdk). Entry point with project setup, contract anatomy, and build/deploy workflow, routing to three companion files in this directory - development.md (storage/TTL, authorization, cross-contract calls, tokens, events, errors, upgrades, fees, troubleshooting), testing.md (unit, fuzz, property, fork, mutation, integration), and security.md (vulnerability classes, checklists, tooling, audits). Use when writing, testing, reviewing, securing, debugging, or shipping Stellar smart contracts, including anything the user calls "Soroban" - Soroban contracts, soroban-sdk, Soroban auth/storage/TTL errors, SEP-41 tokens, or SAC integration from contract code.

★ 6