Merge branch 'main' into feature/104-contract-restoration

Author: Dantama022

README.md

@@ -111,6 +111,11 @@ The repository currently includes the following runnable examples:
 63. **`70-soroban-authorization`**: Invoking an authorized Soroban contract method, obtaining and signing authorization entries from simulation, and explaining how authorization differs from transaction signatures.
 64. **`71-soroban-storage-update`**: Demonstrating the complete lifecycle of a Soroban storage update — reading initial state, simulating and submitting the modifying transaction, polling for confirmation, and verifying the updated value.
 65. **`104-contract-restoration`**: Detecting archived Soroban contract ledger entries, building and simulating a `RestoreFootprint` transaction, submitting restoration when required, and verifying the contract becomes accessible again — with guidance on TTL extension versus restoration.
+65. **`106-scval-serialization`**: Converting JavaScript values to Soroban ScVal objects and back with reusable helpers, displaying raw XDR, and explaining common serialization pitfalls.
+65. **`105-contract-event-decoding`**: Retrieving Soroban contract events and decoding indexed topics and data payloads into human-readable values, with raw base64 XDR shown alongside decoded output.
+65. **`107-contract-spec-introspection`**: Retrieving on-chain WASM, parsing Soroban ScSpec metadata, and displaying functions, arguments, return types, user-defined types, and documentation with dynamic function selection.
+65. **`81-transaction-preflight`**: Running the full Soroban preflight workflow — simulating an invocation, extracting the footprint/authorization/resource-fee data, assembling, signing, submitting, and confirming the final transaction.
+65. **`83-multi-contract-transaction`**: Composing a single orchestrator contract invocation that touches multiple downstream contracts, simulating and submitting it, and explaining atomicity and execution order across contracts within one Soroban host invocation.
 
 ## Installation
 
@@ -444,6 +449,65 @@ npm run run-example -- 104-contract-restoration <contract-id>
 ```
 
 The same contract ID can be supplied through `CONTRACT_ID`. For accessible contracts the example simulates restoration and reports the estimated fee and footprint without submitting an unnecessary transaction. When simulation detects archived entries (`isSimulationRestore`), it prepares, submits, and polls a `RestoreFootprint` transaction, then re-checks accessibility. The output explains the difference between proactive `extendFootprintTtl` and reactive `restoreFootprint`.
+Convert JavaScript values to Soroban ScVal and back:
+
+```bash
+npm run run-example 106-scval-serialization
+```
+
+This offline example encodes booleans, integers, BigInts, strings, symbols, bytes, addresses, vectors, maps, and nested objects using `src/utils/scval-utils.ts`, prints raw base64 XDR for each value, compares originals with decoded round-trip results, and demonstrates graceful handling of unsupported JavaScript types.
+Decode Soroban contract event topics and payloads:
+
+```bash
+npm run run-example 105-contract-event-decoding
+```
+
+Query a specific contract, start ledger, and limit:
+
+```bash
+npm run run-example -- 105-contract-event-decoding <contract-id> <start-ledger> 10
+```
+
+The same values can be supplied through `CONTRACT_ID`, `START_LEDGER`, and `EVENT_LIMIT`. For each event the example prints the contract ID, ledger sequence, transaction hash, every topic and the data payload with raw base64 XDR beside the decoded value. Unsupported ScVal types are reported without aborting the run.
+Inspect a Soroban contract specification from on-chain WASM:
+
+```bash
+npm run run-example 107-contract-spec-introspection
+```
+
+Select a contract and function dynamically:
+
+```bash
+npm run run-example -- 107-contract-spec-introspection <contract-id> balance
+```
+
+The same values can be supplied through `CONTRACT_ID` and `CONTRACT_FUNCTION`. The example fetches WASM via Soroban RPC, parses ScSpec metadata with `spec-parser` utilities, lists functions, structs, enums, unions, and error enums, and shows how SDK tooling and explorers use the same metadata. Missing or empty specifications are reported gracefully.
+Run the full Soroban transaction preflight workflow:
+
+```bash
+npm run run-example 81-transaction-preflight
+```
+
+Supply a custom contract ID and method via environment variables:
+
+```bash
+CONTRACT_ID=<contract-id> CONTRACT_METHOD=<method> npm run run-example 81-transaction-preflight
+```
+
+The example funds an ephemeral fee-payer account, builds a contract invocation transaction, and submits it for preflight simulation to extract the ledger footprint, authorization entries, and estimated resource fee. It then assembles the final transaction from that simulation data, signs and submits it, and polls until on-chain confirmation — while also explaining how a full preflight (simulate → assemble → sign → submit) differs from an ordinary read-only simulation that is never meant to be submitted, and reporting any preflight failures with clear, actionable guidance.
+Compose a multi-contract transaction through an orchestrator invocation:
+
+```bash
+npm run run-example 83-multi-contract-transaction
+```
+
+Supply a custom orchestrator and downstream contract IDs:
+
+```bash
+CONTRACT_ID=<orchestrator-id> CONTRACT_ID_A=<contract-a-id> CONTRACT_ID_B=<contract-b-id> npm run run-example 83-multi-contract-transaction
+```
+
+Soroban only allows a single host-function (contract invocation) operation per transaction, so "multiple contract invocations in one transaction" is achieved by invoking one orchestrator/router contract whose method internally makes cross-contract calls into other contracts, rather than by adding several top-level `contract.call(...)` operations. The example builds that single orchestrator invocation with two downstream contract IDs as arguments, simulates it to display the combined resource footprint and authorization entries spanning every contract touched, signs and submits it, and explains why a failure anywhere in the call chain — including a downstream cross-contract call — rolls back the entire transaction atomically, and why execution order follows the orchestrator's own code path rather than the order arguments are listed.
 
 _Note: You can configure custom environment variables in a local `.env` file, including `HORIZON_URL`, `SOROBAN_RPC_URL`, `NETWORK_PASSPHRASE`, and `TRANSACTION_HASH`._
 

src/examples/105-contract-event-decoding.ts

@@ -0,0 +1,160 @@
+import { rpc, StrKey } from '@stellar/stellar-sdk';
+
+import {
+  compareScVal,
+  decodePayload,
+  decodeTopics,
+  formatEventDecodingReport,
+} from '../utils/scval-decoder';
+
+/**
+ * Example 105: Soroban Contract Event Decoding
+ *
+ * Contract events carry topics (indexed ScVals) and a data payload (one ScVal).
+ * This example retrieves events for a contract and decodes every topic and the
+ * payload into human-readable values, showing raw base64 XDR alongside decoded
+ * output for side-by-side comparison.
+ */
+
+const DEFAULT_RPC_URL = 'https://soroban-testnet.stellar.org';
+const DEFAULT_CONTRACT_ID = 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC';
+const DEFAULT_LOOKBACK = 17280;
+const DEFAULT_LIMIT = 5;
+
+export interface ContractEventDecodingParams {
+  contractId?: string;
+  startLedger?: number | string;
+  limit?: number | string;
+  rpcUrl?: string;
+}
+
+export function normalizeContractId(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error('Missing contract ID. Provide a contract ID starting with "C".');
+  }
+  if (!StrKey.isValidContract(trimmed)) {
+    throw new Error(`Invalid contract ID "${trimmed}".`);
+  }
+  return trimmed;
+}
+
+export function normalizeLimit(value?: number | string): number {
+  const parsed = typeof value === 'string' ? parseInt(value.trim(), 10) : value;
+  if (parsed === undefined || Number.isNaN(parsed)) return DEFAULT_LIMIT;
+  return Math.min(Math.max(Math.trunc(parsed), 1), 50);
+}
+
+export function parseLedgerInput(value?: number | string): number | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  const parsed = typeof value === 'string' ? parseInt(value.trim(), 10) : value;
+  if (Number.isNaN(parsed) || parsed < 1) return undefined;
+  return Math.trunc(parsed);
+}
+
+export async function run(params: ContractEventDecodingParams = {}): Promise<void> {
+  const rpcUrl = params.rpcUrl || process.env.SOROBAN_RPC_URL || DEFAULT_RPC_URL;
+  const contractInput =
+    params.contractId?.trim() ||
+    process.env.CONTRACT_ID?.trim() ||
+    process.argv[3]?.trim() ||
+    DEFAULT_CONTRACT_ID;
+  const limit = normalizeLimit(params.limit ?? process.env.EVENT_LIMIT ?? process.argv[5]);
+  const startInput = parseLedgerInput(
+    params.startLedger ?? process.env.START_LEDGER ?? process.argv[4],
+  );
+
+  console.log('Soroban Contract Event Decoding Example');
+  console.log(`Soroban RPC: ${rpcUrl}`);
+
+  let contractId: string;
+  try {
+    contractId = normalizeContractId(contractInput);
+  } catch (err: any) {
+    console.log(`\n${err?.message ?? err}`);
+    return;
+  }
+
+  const server = new rpc.Server(rpcUrl);
+
+  let latestLedger: number;
+  try {
+    latestLedger = (await server.getLatestLedger()).sequence;
+    console.log(`Latest ledger: ${latestLedger}`);
+  } catch (err: any) {
+    console.log(`Could not reach Soroban RPC: ${err?.message ?? err}`);
+    return;
+  }
+
+  const startLedger = startInput ?? Math.max(1, latestLedger - DEFAULT_LOOKBACK);
+  console.log(`Contract: ${contractId}`);
+  console.log(`Ledger range: ${startLedger} -> latest (limit ${limit})`);
+
+  let response: rpc.Api.GetEventsResponse;
+  try {
+    response = await server.getEvents({
+      startLedger,
+      filters: [{ type: 'contract', contractIds: [contractId] }],
+      limit,
+    });
+  } catch (err: any) {
+    console.log(`\nCould not retrieve events: ${err?.message ?? err}`);
+    return;
+  }
+
+  const events = response.events ?? [];
+  if (events.length === 0) {
+    console.log('\nNo contract events found in the queried ledger range.');
+    console.log('This is a valid empty result — try a more recent start ledger or another contract.');
+    return;
+  }
+
+  console.log(`\nRetrieved ${events.length} event(s). Decoding topics and payloads...\n`);
+
+  events.forEach((event, index) => {
+    console.log(formatEventDecodingReport({
+      contractId,
+      ledger: event.ledger ?? 0,
+      txHash: event.txHash ?? '',
+      topics: event.topic ?? [],
+      value: event.value,
+    }));
+
+    const topicComparisons = (event.topic ?? []).map(compareScVal);
+    const payloadComparison = compareScVal(event.value);
+
+    console.log('\nSide-by-side summary:');
+    topicComparisons.forEach((row, topicIndex) => {
+      console.log(
+        `  topic[${topicIndex}] ${row.xdrType.padEnd(12)} raw=${row.rawXdr.slice(0, 24)}… decoded=${row.decodedDisplay}`,
+      );
+    });
+    console.log(
+      `  payload     ${payloadComparison.xdrType.padEnd(12)} raw=${payloadComparison.rawXdr.slice(0, 24)}… decoded=${payloadComparison.decodedDisplay}`,
+    );
+
+    const decodedTopics = decodeTopics(event.topic);
+    const decodedPayload = decodePayload(event.value);
+    const unsupported = [...decodedTopics, decodedPayload].filter((item) => !item.decoded);
+    if (unsupported.length > 0) {
+      console.log('\nUnsupported or undecodable values:');
+      unsupported.forEach((item) => {
+        console.log(`  - ${item.xdrType}: ${item.error ?? 'decode failed'}`);
+      });
+    }
+
+    if (index < events.length - 1) {
+      console.log('\n' + '-'.repeat(72));
+    }
+  });
+
+  console.log('\nDecoding reference:');
+  console.log('  Address  -> G… or C… strkey');
+  console.log('  Symbol   -> short identifier string');
+  console.log('  String   -> UTF-8 text');
+  console.log('  Bool     -> true / false');
+  console.log('  Integer  -> string (preserves i128/u256 precision)');
+  console.log('  Bytes    -> 0x-prefixed hex');
+  console.log('  Vec/Map  -> JSON array or object');
+  console.log('\nContract event decoding example completed.');
+}

src/examples/106-scval-serialization.ts

@@ -0,0 +1,110 @@
+import { Keypair } from '@stellar/stellar-sdk';
+import chalk from 'chalk';
+
+import {
+  describeUnsupportedJsType,
+  encodeNested,
+  roundTrip,
+  trySerialize,
+} from '../utils/scval-utils';
+
+/**
+ * Example 106: ScVal Serialization and Deserialization
+ *
+ * Soroban contracts exchange data as XDR-encoded ScVal values. This example
+ * demonstrates converting common JavaScript values to ScVal and back using
+ * reusable helpers, displaying raw base64 XDR, and comparing originals with
+ * decoded round-trip results.
+ */
+
+interface DemoCase {
+  label: string;
+  value: unknown;
+  hint: { type: string; element?: { type: string }; key?: { type: string }; value?: { type: string } };
+}
+
+const DEMO_CASES: DemoCase[] = [
+  { label: 'Boolean', value: true, hint: { type: 'bool' } },
+  { label: 'Integer (u32)', value: 42, hint: { type: 'u32' } },
+  { label: 'BigInt (i128)', value: 10_000_000_000n, hint: { type: 'i128' } },
+  { label: 'String', value: 'hello Soroban', hint: { type: 'string' } },
+  { label: 'Symbol', value: 'transfer', hint: { type: 'symbol' } },
+  { label: 'Bytes', value: Buffer.from('cafebabe', 'hex'), hint: { type: 'bytes' } },
+  {
+    label: 'Address',
+    value: Keypair.random().publicKey(),
+    hint: { type: 'address' },
+  },
+  {
+    label: 'Vector<u32>',
+    value: [1, 2, 3, 5, 8],
+    hint: { type: 'vec', element: { type: 'u32' } },
+  },
+  {
+    label: 'Map<symbol,u32>',
+    value: [
+      ['alice', 100],
+      ['bob', 250],
+    ],
+    hint: { type: 'map', key: { type: 'symbol' }, value: { type: 'u32' } },
+  },
+];
+
+function printRoundTrip(result: ReturnType<typeof roundTrip>): void {
+  console.log(`  original : ${JSON.stringify(result.original)}`);
+  console.log(`  xdr type : ${chalk.cyan(result.encoded.xdrType)}`);
+  console.log(`  raw XDR  : ${result.encoded.rawXdr}`);
+  console.log(`  decoded  : ${JSON.stringify(result.decoded)}`);
+  console.log(
+    result.matches
+      ? chalk.green('  match    : yes')
+      : chalk.yellow('  match    : no (see serialization pitfalls below)'),
+  );
+}
+
+export function explainSerializationPitfalls(): string {
+  return [
+    'Serialization pitfalls:',
+    '  - JavaScript numbers above 2^53-1 must use BigInt for u64/i128/u256 types.',
+    '  - Symbol (scvSymbol) is not the same as String (scvString); contracts validate strictly.',
+    '  - Soroban maps decode to [key, value][] arrays, not plain objects, unless reshaped.',
+    '  - Option<T> uses scvVoid for None; undefined is not a valid ScVal input.',
+    '  - Passing the wrong hint throws before any RPC call — validate locally first.',
+  ].join('\n');
+}
+
+export async function run(): Promise<void> {
+  console.log(chalk.bold('ScVal Serialization and Deserialization Example'));
+  console.log(chalk.gray('Offline round-trip encoding using reusable scval-utils helpers.\n'));
+
+  console.log(chalk.bold('Primitive and collection types'));
+  for (const demo of DEMO_CASES) {
+    console.log(chalk.yellow(`\n${demo.label}`));
+    printRoundTrip(roundTrip(demo.value, demo.hint));
+  }
+
+  console.log(chalk.bold('\nNested object (manual scvMap construction)'));
+  const nested = {
+    active: true,
+    count: 3,
+    label: 'nested',
+    scores: [10, 20, 30],
+    meta: { version: 2, owner: 'alice' },
+  };
+  const nestedScVal = encodeNested(nested);
+  console.log(`  original : ${JSON.stringify(nested)}`);
+  console.log(`  xdr type : ${chalk.cyan(nestedScVal.switch().name)}`);
+  console.log(`  raw XDR  : ${nestedScVal.toXDR('base64')}`);
+
+  console.log(chalk.bold('\nUnsupported JavaScript types'));
+  for (const bad of [undefined, () => 'noop', new Date()]) {
+    const attempt = trySerialize(bad, { type: 'u32' });
+    if (!attempt.ok) {
+      console.log(chalk.red(`  ✗ ${describeUnsupportedJsType(bad)}`));
+      console.log(chalk.gray(`    encoder error: ${attempt.error}`));
+    }
+  }
+
+  console.log('\n' + explainSerializationPitfalls());
+  console.log(chalk.green('\nScVal serialization example completed.'));
+}