perf(kapp): zero-copy GetAndClearReturnData + pre-size receipt filters (#45)

* perf(kapp): zero-copy GetAndClearReturnData + pre-size receipt filters

Two related allocation reductions in core/kapp/context.go.

1. GetAndClearReturnData: move semantics instead of deep copy

   The function deep-copied k.returnData into a fresh slice and then
   reset k.returnData to empty. Both call sites
   (blockChainHook.ProcessBuiltInFunction and the kvm world wrapper)
   assign the result straight into vmOutput.ReturnData and never
   touch the context's slice afterward, so the deep copy was guarding
   against an aliasing scenario that cannot occur:

     - The context's slice is reset on the same call.
     - SetReturnData and AddReturnData both allocate fresh storage on
       every write, so the context never re-aliases the returned
       slice.

   Replace the deep copy with ownership transfer. Keep the original
   non-nil-empty invariant for both the returned slice and the field:
   VMOutputApi carries a json:"returnData" tag (nil renders as null,
   [] renders as []), so downstream API consumers can distinguish.

   Get cost drops to O(1) regardless of payload shape.

   Bench (Apple M4 Max, darwin/arm64), Get cost (combined - Set):

     shape          before          after        allocs (before -> after)
     1 x 32 B        22.5 ns         ~0          2 -> 0
     5 x 32 B        75.3 ns         ~0          6 -> 0
     10 x 64 B       175  ns         ~0         11 -> 0
     50 x 256 B     1686  ns         ~0         51 -> 0
     1 x 4096 B      434  ns         ~0          2 -> 0

   The savings scale with return-data payload size. Hot for SC TX
   paths that emit many or large return values (view functions,
   batch operations, mint/transfer arrays).

   SetReturnData and AddReturnData still deep-copy on input. Their
   defensive copies guard against caller-side mutation of the source
   slice and were left unchanged: the gain from removing them is
   smaller than the risk of a future caller silently aliasing.

2. ReceiptSlice.GetByType / GetPreserved: pre-size filtered slice

   Both started with `var filtered []*X`, so the first append
   allocated and subsequent grows reallocated (log2(N) backing
   arrays). Pre-size capacity to len(*r) so the filter is bounded to
   one allocation regardless of match count. Worst case == prior
   memory; best case == fewer allocs. No nil-vs-empty caller
   sensitivity (all callers use len() or range).

Adds three unit tests (none existed for the returnData lifecycle):

  - TestKappContext_ReturnData_RoundTrip exercises Set -> Get ->
    empty -> Add -> Get on a single context.
  - TestKappContext_ReturnData_GetNeverReturnsNil pins the
    JSON-visible invariant that Get always returns a non-nil slice.
  - TestKappContext_ReturnData_GetIsolatesFromFutureWrites pins the
    invariant that the slice handed to the caller is never mutated
    by subsequent context writes (guards the move-semantics
    optimization against future regressions).

Adds context_returndata_bench_test.go with both Get and Set isolated
across realistic SC return shapes.

* chore(kapp): remove unused benchmark helper

newCtxWithReturnData was introduced for benchmark setup but ended up
unused once both benchmarks constructed their contexts inline. Flagged
by golangci-lint (unused) in PR #45 review.

Author: fbsobreira

core/kapp/context.go

@@ -46,7 +46,7 @@ func (r *ReceiptSlice) Get() []*transaction.Transaction_Receipt {
 }
 
 func (r *ReceiptSlice) GetByType(receiptType int8) []*transaction.Transaction_Receipt {
-	var filtered []*transaction.Transaction_Receipt
+	filtered := make([]*transaction.Transaction_Receipt, 0, len(*r))
 	for _, receipt := range *r {
 		if len(receipt.Data) > 0 && len(receipt.Data[0]) > 0 && int8(receipt.Data[0][0]) == receiptType {
 			filtered = append(filtered, receipt)
@@ -56,7 +56,7 @@ func (r *ReceiptSlice) GetByType(receiptType int8) []*transaction.Transaction_Re
 }
 
 func (r *ReceiptSlice) GetPreserved() []*transaction.Transaction_Receipt {
-	var filtered []*transaction.Transaction_Receipt
+	filtered := make([]*transaction.Transaction_Receipt, 0, len(*r))
 	for _, receipt := range *r {
 		if len(receipt.Data) > 0 && len(receipt.Data[0]) > 0 && receipt.Data[0][0] >= SystemReceiptTypeStart {
 			filtered = append(filtered, receipt)
@@ -150,19 +150,22 @@ func (k *kappContext) AddReturnData(data []byte) {
 }
 
 func (k *kappContext) GetAndClearReturnData() [][]byte {
-	// Create a new outer slice with the same length as src
-	dst := make([][]byte, len(k.returnData))
-
-	// Iterate over each inner slice
-	for i, s := range k.returnData {
-		// Create a new inner slice with the same length as s
-		dst[i] = make([]byte, len(s))
-		// Copy the bytes from s to dst[i]
-		copy(dst[i], s)
+	// Move semantics: ownership of returnData transfers to the caller and
+	// the context resets to a fresh empty slice. SetReturnData and
+	// AddReturnData both allocate fresh storage on every write, so no
+	// aliasing of the returned slice remains via this struct.
+	//
+	// Preserve the original guarantee that this method never returns nil
+	// and that the field is non-nil-empty after the call: VMOutputApi
+	// carries a json:"returnData" tag, where nil JSON-renders to null
+	// while []byte{} renders to []. Downstream API consumers may
+	// distinguish.
+	out := k.returnData
+	if out == nil {
+		out = [][]byte{}
 	}
-
 	k.returnData = make([][]byte, 0)
-	return dst
+	return out
 }
 
 func (k *kappContext) GetExecData() []byte {

core/kapp/context_returndata_bench_test.go

@@ -0,0 +1,88 @@
+package kapp_test
+
+import (
+	"crypto/rand"
+	"fmt"
+	"testing"
+
+	"github.com/klever-io/klever-go/core/kapp"
+	"github.com/klever-io/klever-go/data/block"
+)
+
+// genReturnData returns n byte slices of size bytes each, populated with
+// random data so the compiler can't constant-fold the copies away.
+func genReturnData(n, size int) [][]byte {
+	out := make([][]byte, n)
+	for i := range out {
+		out[i] = make([]byte, size)
+		_, _ = rand.Read(out[i])
+	}
+	return out
+}
+
+// BenchmarkGetAndClearReturnData measures the per-call cost of pulling
+// return data out of the context. Sweep across realistic SC return shapes:
+//
+//   - (1, 32)     — single small item (typical: assetID, proposalID, orderID)
+//   - (5, 32)     — small array of small items (typical: minted-token IDs)
+//   - (10, 64)    — moderate array of moderate items (e.g., transfer batch IDs)
+//   - (50, 256)   — large array (uncommon but plausible for view fns)
+//   - (1, 4096)   — single large item (e.g., serialized struct)
+func BenchmarkGetAndClearReturnData(b *testing.B) {
+	cases := []struct{ n, size int }{
+		{1, 32},
+		{5, 32},
+		{10, 64},
+		{50, 256},
+		{1, 4096},
+	}
+	for _, c := range cases {
+		b.Run(fmt.Sprintf("n=%d/size=%d", c.n, c.size), func(b *testing.B) {
+			// Refill the context every call so each iteration has data
+			// to drain. We measure GetAndClearReturnData *plus* the refill
+			// (SetReturnData), then subtract the refill cost separately.
+			data := genReturnData(c.n, c.size)
+			ctx := kapp.NewKappContext(kapp.ArgsNewKAppContext{
+				OriginalSender: []byte("sender"),
+				ContractID:     0,
+				Block:          &block.Block{},
+			})
+
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				ctx.SetReturnData(data)
+				_ = ctx.GetAndClearReturnData()
+			}
+		})
+	}
+}
+
+// BenchmarkSetReturnData_Only isolates the refill cost so the
+// GetAndClearReturnData number above can be interpreted (subtract this
+// from the combined number to get the Get cost alone).
+func BenchmarkSetReturnData_Only(b *testing.B) {
+	cases := []struct{ n, size int }{
+		{1, 32},
+		{5, 32},
+		{10, 64},
+		{50, 256},
+		{1, 4096},
+	}
+	for _, c := range cases {
+		b.Run(fmt.Sprintf("n=%d/size=%d", c.n, c.size), func(b *testing.B) {
+			data := genReturnData(c.n, c.size)
+			ctx := kapp.NewKappContext(kapp.ArgsNewKAppContext{
+				OriginalSender: []byte("sender"),
+				ContractID:     0,
+				Block:          &block.Block{},
+			})
+
+			b.ReportAllocs()
+			b.ResetTimer()
+			for i := 0; i < b.N; i++ {
+				ctx.SetReturnData(data)
+			}
+		})
+	}
+}

core/kapp/context_test.go

@@ -1,6 +1,7 @@
 package kapp_test
 
 import (
+	"bytes"
 	"testing"
 	"time"
 
@@ -76,6 +77,99 @@ func TestKappContext_ExecutionTimeStorage(t *testing.T) {
 	assert.Equal(t, executionTime, retrieved)
 }
 
+// TestKappContext_ReturnData_RoundTrip exercises the returnData lifecycle:
+// SetReturnData -> GetAndClearReturnData empties the context, the returned
+// slice exposes the stored payload, and re-using the context after a Get
+// works (Add/Set on a freshly cleared context behave identically to a
+// brand-new context).
+func TestKappContext_ReturnData_RoundTrip(t *testing.T) {
+	t.Parallel()
+
+	ctx := kapp.NewKappContext(kapp.ArgsNewKAppContext{
+		OriginalSender: []byte("sender"),
+		ContractID:     0,
+		Block:          &block.Block{},
+	})
+
+	// initial Get on empty context returns an empty slice
+	first := ctx.GetAndClearReturnData()
+	assert.Empty(t, first, "fresh context has no return data")
+
+	payload := [][]byte{
+		[]byte("alpha"),
+		[]byte("beta"),
+		[]byte("gamma"),
+	}
+	ctx.SetReturnData(payload)
+
+	out := ctx.GetAndClearReturnData()
+	assert.Equal(t, payload, out, "Get returns the previously Set payload")
+
+	// context is empty after Get
+	again := ctx.GetAndClearReturnData()
+	assert.Empty(t, again, "context cleared after Get")
+
+	// reuse: Add after a Get works
+	ctx.AddReturnData([]byte("delta"))
+	ctx.AddReturnData([]byte("epsilon"))
+	out2 := ctx.GetAndClearReturnData()
+	assert.Equal(t, [][]byte{[]byte("delta"), []byte("epsilon")}, out2)
+}
+
+// TestKappContext_ReturnData_GetNeverReturnsNil pins the invariant that
+// GetAndClearReturnData always returns a non-nil slice — matching the
+// original implementation's `make([][]byte, 0)` reset. VMOutputApi carries
+// a `json:"returnData"` tag, so a nil slice would JSON-render as null
+// while an empty slice renders as []; downstream API consumers can
+// distinguish.
+func TestKappContext_ReturnData_GetNeverReturnsNil(t *testing.T) {
+	t.Parallel()
+
+	ctx := kapp.NewKappContext(kapp.ArgsNewKAppContext{
+		OriginalSender: []byte("sender"),
+		ContractID:     0,
+		Block:          &block.Block{},
+	})
+
+	first := ctx.GetAndClearReturnData()
+	assert.NotNil(t, first, "Get on a fresh context returns non-nil")
+	assert.Empty(t, first)
+
+	ctx.SetReturnData([][]byte{[]byte("payload")})
+	_ = ctx.GetAndClearReturnData() // drain
+
+	second := ctx.GetAndClearReturnData()
+	assert.NotNil(t, second, "Get on a drained context returns non-nil")
+	assert.Empty(t, second)
+}
+
+// TestKappContext_ReturnData_GetIsolatesFromFutureWrites guards against a
+// regression of the move-semantics optimization: the slice returned to the
+// caller must not be observably mutated by subsequent Set/Add on the same
+// context (the context allocates fresh storage on each Set/Add, so the
+// returned slice keeps pointing at the prior payload).
+func TestKappContext_ReturnData_GetIsolatesFromFutureWrites(t *testing.T) {
+	t.Parallel()
+
+	ctx := kapp.NewKappContext(kapp.ArgsNewKAppContext{
+		OriginalSender: []byte("sender"),
+		ContractID:     0,
+		Block:          &block.Block{},
+	})
+
+	ctx.SetReturnData([][]byte{[]byte("first")})
+	out := ctx.GetAndClearReturnData()
+
+	// Subsequent context writes must not bleed into the previously
+	// returned slice.
+	ctx.SetReturnData([][]byte{[]byte("second"), []byte("third")})
+	ctx.AddReturnData([]byte("fourth"))
+
+	assert.Equal(t, 1, len(out), "previously returned slice length is stable")
+	assert.True(t, bytes.Equal(out[0], []byte("first")),
+		"previously returned bytes are stable")
+}
+
 // TestReceiptSlice_GetByType tests filtering receipts by type
 func TestReceiptSlice_GetByType(t *testing.T) {
 	t.Parallel()