feat: add Soroban token, authorization, footprint, and resource analysis examples

[InfamousCanary]

Summary

This PR adds four advanced Soroban examples covering token contract interaction, authorization inspection, ledger footprints, and transaction resource/fee analysis.

Added

• 116-soroban-token-contract

  • Connects to Soroban RPC
  • Inspects token metadata including name, symbol, and decimals
  • Retrieves balances and allowances
  • Handles optional total_supply
  • Constructs and simulates token transfers
  • Decodes returned ScVal values
  • Handles invalid contract IDs and insufficient-balance scenarios
  • Explains the relationship between Stellar assets and Stellar Asset Contracts

• 117-soroban-auth-tree

  • Builds and simulates an invocation requiring authorization
  • Extracts authorization entries returned by simulation
  • Displays root and nested authorization invocations hierarchically
  • Shows required signer, contract ID, function name, arguments, and signature status
  • Decodes common ScVal argument types
  • Uses iterative traversal to safely handle deeply nested authorization trees
  • Handles empty authorization results and simulation failures

• 118-ledger-footprint-analysis

  • Simulates two Soroban contract invocations
  • Extracts and analyzes their ledger footprints
  • Separates read-only and read-write entries
  • Decodes ledger keys where supported
  • Identifies persistent, temporary, instance, and contract-code entries
  • Displays raw XDR for detailed inspection
  • Summarizes footprint size and compares two successful invocations
  • Handles empty footprints, restore-required responses, and simulation failures

• 119-soroban-resource-fee-analysis

  • Simulates and compares two Soroban contract invocations
  • Reports CPU and memory information where exposed by the RPC node
  • Handles unavailable CPU/memory information gracefully
  • Displays ledger read/write counts and ledger I/O limits
  • Displays transaction instruction limits
  • Separates Soroban resource fees from the inclusion/base fee
  • Calculates total estimated transaction cost
  • Shows relative resource and fee contribution percentages
  • Compares resource usage across two invocations
  • Highlights unusually expensive resource usage
  • Explains how simulation contributes to transaction preparation

Runner and Documentation

• Registered all four examples in the interactive runner
• Added all four examples to the README example catalog
• Added focused tests covering examples 116–119
• Included the minimal existing catalog syntax correction required for the runner catalog to compile and allow the new registrations

Validation

The following checks passed:

• npx tsc --noEmit
• ESLint for all added/modified example and test files
• Prettier formatting
• git diff --check
• 41/41 targeted tests passed

Live runner validation completed successfully for:

• npm run run-example 116-soroban-token-contract
• npm run run-example 117-soroban-auth-tree
• npm run run-example 118-ledger-footprint-analysis
• npm run run-example 119-soroban-resource-fee-analysis

The live footprint and resource examples successfully simulated and compared two contract invocations.

The public Testnet RPC used during validation did not expose CPU instruction or memory-consumption values. Example 119 therefore displayed those fields as unavailable while continuing to report transaction resource limits, ledger access, fee components, estimated total cost, and invocation comparison as intended.

No transactions are signed or submitted by these examples; contract operations are simulation-only.

Closes #163
Closes #164
Closes #165
Closes #166

[drips-wave]

@InfamousCanary Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits