From 96081e07ff90ef2fa9c96b2185619e11b826062a Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Thu, 2 Apr 2026 05:12:44 -0400
Subject: [PATCH] docs: add recursive function call tracing example

Add a recursive count/succ example to the tracing docs,
showing how nested invoke/return contexts appear when
functions call themselves repeatedly.
---
 .../core-schemas/programs/tracing-examples.ts | 27 +++++++++++++++++++
 .../docs/core-schemas/programs/tracing.mdx    | 12 +++++++++
 2 files changed, 39 insertions(+)

diff --git a/packages/web/docs/core-schemas/programs/tracing-examples.ts b/packages/web/docs/core-schemas/programs/tracing-examples.ts
index 63b1a4b6f..12013c33e 100644
--- a/packages/web/docs/core-schemas/programs/tracing-examples.ts
+++ b/packages/web/docs/core-schemas/programs/tracing-examples.ts
@@ -71,3 +71,30 @@ create {
 code {
   result = add(3, 4);
 }`;
+
+export const recursiveCount = `name Counter;
+
+define {
+  function succ(n: uint256) -> uint256 {
+    return n + 1;
+  };
+  function count(n: uint256, target: uint256) -> uint256 {
+    if (n < target) {
+      return count(succ(n), target);
+    } else {
+      return n;
+    }
+  };
+}
+
+storage {
+  [0] result: uint256;
+}
+
+create {
+  result = 0;
+}
+
+code {
+  result = count(0, 5);
+}`;
diff --git a/packages/web/docs/core-schemas/programs/tracing.mdx b/packages/web/docs/core-schemas/programs/tracing.mdx
index 2cb4f0bdd..125ae3c8f 100644
--- a/packages/web/docs/core-schemas/programs/tracing.mdx
+++ b/packages/web/docs/core-schemas/programs/tracing.mdx
@@ -10,6 +10,7 @@ import {
   thresholdCheck,
   multipleStorageSlots,
   functionCallAndReturn,
+  recursiveCount,
 } from "./tracing-examples";
 
 # Tracing execution
@@ -95,6 +96,17 @@ trace. Watch for **invoke** contexts on the JUMP into `add` and
   source={functionCallAndReturn}
 />
 
+Recursive calls produce nested invoke/return pairs. In this
+example, `count` calls `succ` and then calls itself repeatedly
+until `n` reaches `target`. Each recursive call adds a frame
+to the call stack:
+
+<TraceExample
+  title="Recursive function calls"
+  description="Counts from 0 to 5 using recursive succ and count functions"
+  source={recursiveCount}
+/>
+
 As you step through, three phases are visible:
 
 ### Before the call — setting up arguments