feat: return real result XDR from getTransaction

Receipts now carry a real base64 TransactionResult in resultXdr and
TransactionMeta v3 in resultMetaXdr instead of empty-string stubs.

The semantics record the contract call's return value: uncheckedCallTx
no longer resets the host after the call, so #recordAndRespond can read
the returned ScVal off the hostStack, serialise it into the receipt's
internal returnValue field (JSON-encoded via the new #scValToJSON), and
reset the host afterwards. The server rewrites that field into the
spec-mandated XDR structs (new result_xdr.py builders, scval_from_json
decoder), since K cannot construct XDR. An invocation's return value is
reported as sorobanMeta.returnValue in the meta, matching stellar-rpc.

Failed transactions now store a txFAILED TransactionResult in the
FAILED receipt (resultMetaXdr is omitted: a rolled-back run produces no
meta), keeping ledger/createdAt encoded as on SUCCESS receipts.

Fees and ledger-entry change sets in the synthesised structs are
zero/empty because komet-node does not track them; documented in
docs/notes.md.

Author: RaoulSchaffranek

docs/architecture.md

@@ -89,7 +89,7 @@ All of the server's input and output artifacts live in one directory, the *io di
 |---|---|---|---|
 | `state.kore` | persistent | `NodeInterpreter` | the full K world-state configuration — accounts, contract code (including uploaded wasm `ModuleDecl`s), contract storage, ledger metadata — serialized in KORE. Read before each run and rewritten after a successful one. |
 | `metadata.json` | persistent | the K semantics | `{"latest_ledger": N}` — the server ledger counter, bumped by 1 per committed transaction. |
-| `receipts/receipt_<hash>.json` | persistent | the semantics (on success) or the server (on failure) | one stored receipt per transaction, keyed by tx hash, answering `getTransaction`. Each is `{status, ledger, createdAt, envelopeXdr, resultXdr, resultMetaXdr}`. |
+| `receipts/receipt_<hash>.json` | persistent | the semantics and the server (on success — the server rewrites the semantics' internal `returnValue` field into `resultXdr`/`resultMetaXdr`), or the server alone (on failure) | one stored receipt per transaction, keyed by tx hash, answering `getTransaction`. Each is `{status, ledger, createdAt, envelopeXdr, resultXdr, resultMetaXdr?}`. |
 | `traces/trace_<hash>.jsonl` | persistent | the semantics | one execution trace per transaction, keyed by tx hash — the instruction-level records, one JSON object per line. `traceTransaction` returns this file's contents. |
 | `requests/request_<n>.json` | persistent | the server | an archive of each incoming JSON-RPC request, numbered by a monotonic counter, kept for debugging. |
 | `request.json` | transient | the server | the request envelope for the call in flight (`method`, `id`, `now`, and method-specific fields). The semantics remove it once they respond. |
@@ -175,7 +175,6 @@ sequenceDiagram
 
 ## What's not yet implemented
 
-- `resultXdr` / `resultMetaXdr` in `getTransaction` responses (contract return values)
 - `simulateTransaction` (dry-run without state mutation)
 - `getEvents`, `getLedgerEntries`, `getFeeStats` and other read-only RPC methods
 - `ExtendFootprintTTL` and `RestoreFootprint` operations

docs/node-semantics.md

@@ -83,9 +83,13 @@ If `request.json` is absent, `insert-handleRequestFile` does not fire and K halt
 
 1. writes `metadata.json` with `latest_ledger + 1`,
 2. writes the receipt to `receipts/receipt_<hash>.json`:
-   `{ status: "SUCCESS", ledger, createdAt, envelopeXdr, resultXdr: "", resultMetaXdr: "" }`,
+   `{ status: "SUCCESS", ledger, createdAt, envelopeXdr, returnValue }` — `returnValue` is
+   the contract call's return `ScVal`, JSON-encoded by `#scValToJSON` (or `null` when the
+   transaction made no contract call), read off the `<hostStack>` before the host is reset,
 3. responds with `{hash, status: "PENDING", latestLedger, latestLedgerCloseTime}`.
 
+The internal `returnValue` field never reaches an RPC client: the Python server immediately rewrites it into the spec-mandated `resultXdr`/`resultMetaXdr` base64 XDR fields (`_attach_result_xdr` in `server.py`), because K cannot construct XDR. To keep the return value observable here, `uncheckedCallTx` (unlike komet's `callTx`) does not `#resetHost` after the call; `#recordAndRespond` serialises the stack top and resets the host instead.
+
 The trace is not part of the receipt — the executing steps already appended it to `traces/trace_<hash>.jsonl`. Reaching `#finalizeTx` means the steps completed without getting stuck, so the status is `SUCCESS`. A failed transaction gets stuck before this point, `response.json` is never written, and the Python server records the `FAILED` receipt instead.
 
 ### traceTransaction

docs/notes.md

@@ -33,6 +33,8 @@ The tests do not yet cover `bytes` / `address` SCVal arguments or `SCVec` / `SCM
 
 ## Known gaps
 
-- `resultXdr` / `resultMetaXdr` are empty stubs (contract return values not surfaced).
+- `resultXdr` / `resultMetaXdr` are synthesised: `feeCharged` is 0, ledger-entry change
+  sets are empty, and the InvokeHostFunction success hash covers only the return value
+  (komet-node does not track fees, entry changes, or events).
 - `SCVec` / `SCMap` contract arguments are not yet encoded.
 - `simulateTransaction`, `getEvents`, `getLedgerEntries`, `getFeeStats`, and TTL/footprint operations are not implemented.

docs/server.md

@@ -136,18 +136,20 @@ All methods are answered by the K semantics and follow the [Stellar RPC specific
 ```json
 {
   "status": "SUCCESS", "ledger": "5", "createdAt": "1716000000",
-  "envelopeXdr": "<base64 XDR>", "resultXdr": "", "resultMetaXdr": "",
+  "envelopeXdr": "<base64 XDR>", "resultXdr": "<base64 XDR>", "resultMetaXdr": "<base64 XDR>",
   "latestLedger": "5", "latestLedgerCloseTime": "1716000000"
 }
 ```
 
-`resultXdr` and `resultMetaXdr` are currently empty stubs. The receipt carries no trace — use `traceTransaction` with the same hash to fetch it.
+`resultXdr` is a base64 `TransactionResult` (code `txSUCCESS` or `txFAILED`) and `resultMetaXdr` a base64 `TransactionMeta` v3; when the transaction invoked a contract, its return value is reported as `sorobanMeta.returnValue` inside the meta. Both are synthesised by the server (`result_xdr.py`) from the envelope and the return value the semantics recorded in the receipt — see [node-semantics.md](node-semantics.md). Fees and ledger-entry change sets in these structs are zero/empty (komet-node does not track them). `resultMetaXdr` is omitted on `FAILED` receipts — a failed run rolls back and produces no meta. The receipt carries no trace — use `traceTransaction` with the same hash to fetch it.
 
 ---
 
 ## Failure fallback
 
-A failed transaction leaves the semantics stuck without writing `response.json`, so `interpreter.run` returns `None`. Only `sendTransaction` executes a transaction, so it is the only method that reaches this path. The server then synthesises the response in Python: it writes a `FAILED` `receipts/receipt_<hash>.json` (so a later `getTransaction` finds it), without bumping the ledger, and returns `PENDING`. This is the only response content the server builds itself.
+A failed transaction leaves the semantics stuck without writing `response.json`, so `interpreter.run` returns `None`. Only `sendTransaction` executes a transaction, so it is the only method that reaches this path. The server then synthesises the response in Python: it writes a `FAILED` `receipts/receipt_<hash>.json` (so a later `getTransaction` finds it) with a `txFAILED` `resultXdr` and no `resultMetaXdr`, without bumping the ledger, and returns `PENDING`. `ledger` on a `FAILED` receipt pins the latest ledger at failure time (the chain does not advance) and `createdAt` the submission time, with the same encoding as on `SUCCESS` receipts.
+
+On the success path the server also post-processes the receipt the semantics wrote: `_attach_result_xdr` replaces the receipt's internal `returnValue` field (a JSON-encoded SCVal, or `null`) with the spec-mandated `resultXdr`/`resultMetaXdr` base64 XDR, which K cannot construct. These are the only response contents the server builds itself.
 
 ---
 

src/komet_node/kdist/node.md

@@ -291,6 +291,13 @@ After the steps run, record the receipt, write the new ledger counter, and respo
 was already written to its own file during execution, so we only reset `<ioDir>`. Reaching
 this point means the steps completed without getting stuck, so the status is `SUCCESS`.
 
+The receipt carries the contract call's return value (if the transaction made one): after
+`uncheckedCallTx` runs, the call's result `ScVal` is still sitting on the `<hostStack>` (see
+below), so we serialise it into the receipt's internal `returnValue` field and only then
+reset the host. The Python server immediately rewrites that field into the spec-mandated
+`resultXdr`/`resultMetaXdr` base64 XDR fields (K cannot construct XDR), so `returnValue`
+never reaches an RPC client.
+
 ```k
     rule <k> #finalizeTx( REQ )
           => #recordAndRespond(
@@ -304,22 +311,30 @@ this point means the steps completed without getting stuck, so the status is `SU
     rule <k> #recordAndRespond( REQ, L )
           => #writeFile( "metadata.json", JSON2String({ "latest_ledger" : L +Int 1 }) )
           ~> #writeFile( #receiptFile( #getString( "txHash", REQ ) ),
-                 JSON2String( #txReceipt( REQ, L +Int 1 ) ) )
+                 JSON2String( #txReceipt( REQ, L +Int 1, #returnValueJSON( STACK ) ) ) )
+          ~> #resetHost
           ~> #respondTx( REQ, L +Int 1 )
              ...
          </k>
+         <hostStack> STACK </hostStack>
 
-    syntax JSON ::= #txReceipt( JSON, Int ) [function, symbol(txReceipt)]
- // ---------------------------------------------------------------------
-    rule #txReceipt( REQ, NEWL ) => {
+    syntax JSON ::= #txReceipt( JSON, Int, JSON ) [function, symbol(txReceipt)]
+ // ---------------------------------------------------------------------------
+    rule #txReceipt( REQ, NEWL, RETVAL ) => {
             "status"        : "SUCCESS",
             "ledger"        : Int2String( NEWL ),
             "createdAt"     : #getString( "now", REQ ),
             "envelopeXdr"   : #getString( "envelopeXdr", REQ ),
-            "resultXdr"     : "",
-            "resultMetaXdr" : ""
+            "returnValue"   : RETVAL
         }
 
+    // The return value of the transaction's contract call: the ScVal left on top of the
+    // host stack, or null when the transaction made no contract call.
+    syntax JSON ::= #returnValueJSON( HostStack ) [function, total, symbol(returnValueJSON)]
+ // ----------------------------------------------------------------------------------------
+    rule #returnValueJSON( VAL:ScVal : _ ) => #scValToJSON( VAL )
+    rule #returnValueJSON( _ )             => null                 [owise]
+
     rule <k> #respondTx( REQ, NEWL )
           => #respond( #getJSON( "id", REQ ), {
                  "hash"                  : #getString( "txHash", REQ ),
@@ -419,6 +434,10 @@ SCVal arg encoding (key order also significant):
 
 `uncheckedCallTx` is like komet's `callTx` but it does not entail a return value check.
 
+Unlike `callTx`, it does not `#resetHost` after the call either: the call's return value is
+left on the `<hostStack>` so `#recordAndRespond` can serialise it into the receipt. The host
+is reset there instead (and each `uncheckedCallTx` clears the host cell before it runs, so a
+leftover value never bleeds into a later call).
 
 ```k
     syntax Step ::= uncheckedCallTx( from: Address, to: Address, func: WasmString, args: List)     [symbol(uncheckedCallTx)]
@@ -427,11 +446,67 @@ SCVal arg encoding (key order also significant):
         <k> uncheckedCallTx(FROM, TO, FUNC, ARGS)
          => allocObjects(ARGS)
          ~> callContractFromStack(FROM, TO, FUNC)
-         ~> #resetHost
             ...
         </k>
         // clear the host cell before contract calls
         (_:HostCell => <host> <hostStack> .HostStack </hostStack> ... </host>)
+```
+
+###############################################################################
+# ScVal serialisation
+
+`#scValToJSON` renders an `ScVal` as JSON for the receipt's internal `returnValue` field.
+The encoding mirrors the SCVal *argument* encoding accepted by `#decodeArg` above (and
+produced by `scval_to_json` in `scval.py`), extended with the value-only cases that can come
+back from a contract but never go in as arguments: `void`, `string`, `u256`, `vec`, `map`.
+The Python server decodes it with `scval_from_json` (`scval.py`) — keep the three in sync.
+Values with no JSON encoding (e.g. `Error`) render as `null`, i.e. as "no return value".
+
+```k
+    syntax JSON ::= #scValToJSON( ScVal ) [function, total, symbol(scValToJSON)]
+ // ----------------------------------------------------------------------------
+    rule #scValToJSON( SCBool(B)  ) => { "type" : "bool"   , "value" : B }
+    rule #scValToJSON( Void       ) => { "type" : "void" }
+    rule #scValToJSON( I32(V)     ) => { "type" : "i32"    , "value" : V }
+    rule #scValToJSON( U32(V)     ) => { "type" : "u32"    , "value" : V }
+    rule #scValToJSON( I64(V)     ) => { "type" : "i64"    , "value" : V }
+    rule #scValToJSON( U64(V)     ) => { "type" : "u64"    , "value" : V }
+    rule #scValToJSON( I128(V)    ) => { "type" : "i128"   , "value" : V }
+    rule #scValToJSON( U128(V)    ) => { "type" : "u128"   , "value" : V }
+    rule #scValToJSON( U256(V)    ) => { "type" : "u256"   , "value" : V }
+    rule #scValToJSON( Symbol(S)  ) => { "type" : "symbol" , "value" : S }
+    rule #scValToJSON( ScString(S)) => { "type" : "string" , "value" : S }
+    rule #scValToJSON( ScBytes(B) ) => { "type" : "bytes"  , "value" : #bytesToHex(B) }
+    rule #scValToJSON( ScAddress(Account(B))  ) => { "type" : "address" , "addrType" : "account"  , "value" : #bytesToHex(B) }
+    rule #scValToJSON( ScAddress(Contract(B)) ) => { "type" : "address" , "addrType" : "contract" , "value" : #bytesToHex(B) }
+    rule #scValToJSON( ScVec(L)   ) => { "type" : "vec"    , "value" : [ #scValsToJSONs(L) ] }
+    rule #scValToJSON( ScMap(M)   ) => { "type" : "map"    , "value" : [ #mapToJSONs(keys_list(M), M) ] }
+    rule #scValToJSON( _          ) => null                                     [owise]
+
+    syntax JSONs ::= #scValsToJSONs( List ) [function, symbol(scValsToJSONs)]
+ // -------------------------------------------------------------------------
+    rule #scValsToJSONs( .List ) => .JSONs
+    rule #scValsToJSONs( ListItem(V) REST ) => #scValToJSON({V}:>ScVal) , #scValsToJSONs(REST)
+
+    // Each map entry becomes a two-element [key, value] array, in key order.
+    syntax JSONs ::= #mapToJSONs( List, Map ) [function, symbol(mapToJSONs)]
+ // ------------------------------------------------------------------------
+    rule #mapToJSONs( .List, _ ) => .JSONs
+    rule #mapToJSONs( ListItem(KEY) REST, M )
+      => [ #scValToJSON({KEY}:>ScVal) , #scValToJSON({M[KEY]}:>ScVal) , .JSONs ] , #mapToJSONs(REST, M)
+```
+
+`#bytesToHex` is the inverse of `HexBytes`: lowercase hex, two digits per byte (zero-padded,
+since Base2String drops leading zeroes).
+
+```k
+    syntax String ::= #bytesToHex( Bytes )      [function, total, symbol(bytesToHex)]
+                    | #padZeros( String, Int )  [function, total, symbol(padZeros)]
+ // --------------------------------------------------------------------------------
+    rule #bytesToHex( B ) => #padZeros( Base2String( Bytes2Int(B, BE, Unsigned), 16 ), 2 *Int lengthBytes(B) )
+
+    rule #padZeros( S, N ) => #padZeros( "0" +String S, N ) requires lengthString(S) <Int N
+    rule #padZeros( S, _ ) => S                              [owise]
 
 endmodule
 ```

src/komet_node/result_xdr.py

@@ -0,0 +1,116 @@
+"""Builders for the ``resultXdr`` / ``resultMetaXdr`` receipt fields.
+
+Per the RPC spec, a SUCCESS or FAILED getTransaction response carries the transaction's
+outcome as base64-encoded ``TransactionResult`` and ``TransactionMeta`` XDR structs. The K
+semantics record the outcome (status and, for contract calls, the return value) but cannot
+construct XDR, so the server synthesises these structs from the transaction envelope and the
+recorded return value.
+
+Being a mock chain, komet-node does not track fees or ledger-entry changes, so those parts
+of the structs are empty/zero: ``feeCharged`` is 0 and the meta carries no entry changes.
+The meta is emitted as ``TransactionMeta`` v3, the protocol-22 format (v4 is protocol 23+).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import TYPE_CHECKING
+
+from stellar_sdk import xdr
+from stellar_sdk.operation import CreateAccount, InvokeHostFunction
+
+if TYPE_CHECKING:
+    from stellar_sdk import TransactionEnvelope
+    from stellar_sdk.operation import Operation
+
+
+def transaction_result_xdr(envelope: TransactionEnvelope, return_value: xdr.SCVal | None, *, success: bool) -> str:
+    """Build the base64 ``TransactionResult`` XDR for a transaction's receipt.
+
+    On success every operation reports its success code (with the InvokeHostFunction result
+    carrying a hash derived from the return value). On failure the code is ``txFAILED``; a
+    single trapped InvokeHostFunction operation is reported when the transaction is a plain
+    contract invocation, otherwise the per-operation detail is left empty — the semantics
+    only report that the run got stuck, not which operation trapped.
+    """
+    operations = envelope.transaction.operations
+    if success:
+        code = xdr.TransactionResultCode.txSUCCESS
+        results = [_op_success_result(op, return_value) for op in operations]
+    else:
+        code = xdr.TransactionResultCode.txFAILED
+        results = _op_failure_results(operations)
+    result = xdr.TransactionResult(
+        fee_charged=xdr.Int64(0),
+        result=xdr.TransactionResultResult(code=code, results=results),
+        ext=xdr.TransactionResultExt(0),
+    )
+    return result.to_xdr()
+
+
+def transaction_meta_xdr(envelope: TransactionEnvelope, return_value: xdr.SCVal | None) -> str:
+    """Build the base64 ``TransactionMeta`` (v3) XDR for a successful transaction's receipt.
+
+    When the transaction made a contract call, its return value is reported as
+    ``sorobanMeta.returnValue`` — this is where clients read an invocation's result. Other
+    soroban transactions (upload, deploy) carry no soroban meta; ledger-entry change sets
+    are empty because komet-node does not track them.
+    """
+    soroban_meta = None
+    if return_value is not None:
+        soroban_meta = xdr.SorobanTransactionMeta(
+            ext=xdr.SorobanTransactionMetaExt(0),
+            events=[],
+            return_value=return_value,
+            diagnostic_events=[],
+        )
+    meta = xdr.TransactionMeta(
+        v=3,
+        v3=xdr.TransactionMetaV3(
+            ext=xdr.ExtensionPoint(0),
+            tx_changes_before=xdr.LedgerEntryChanges([]),
+            operations=[xdr.OperationMeta(xdr.LedgerEntryChanges([])) for _ in envelope.transaction.operations],
+            tx_changes_after=xdr.LedgerEntryChanges([]),
+            soroban_meta=soroban_meta,
+        ),
+    )
+    return meta.to_xdr()
+
+
+def _op_success_result(op: Operation, return_value: xdr.SCVal | None) -> xdr.OperationResult:
+    """The success ``OperationResult`` for one operation of a committed transaction."""
+    if isinstance(op, CreateAccount):
+        tr = xdr.OperationResultTr(
+            xdr.OperationType.CREATE_ACCOUNT,
+            create_account_result=xdr.CreateAccountResult(xdr.CreateAccountResultCode.CREATE_ACCOUNT_SUCCESS),
+        )
+    elif isinstance(op, InvokeHostFunction):
+        # The real network puts SHA-256(InvokeHostFunctionSuccessPreImage) here — a hash over
+        # the emitted events and the return value. komet-node does not capture events, so the
+        # hash is derived from the return value alone (empty for upload/deploy operations).
+        payload = return_value.to_xdr_bytes() if return_value is not None else b''
+        tr = xdr.OperationResultTr(
+            xdr.OperationType.INVOKE_HOST_FUNCTION,
+            invoke_host_function_result=xdr.InvokeHostFunctionResult(
+                xdr.InvokeHostFunctionResultCode.INVOKE_HOST_FUNCTION_SUCCESS,
+                success=xdr.Hash(hashlib.sha256(payload).digest()),
+            ),
+        )
+    else:
+        # TransactionEncoder only admits CreateAccount and InvokeHostFunction operations, so
+        # a committed transaction cannot contain anything else.
+        raise NotImplementedError(f'No result encoding for operation type: {type(op).__name__}')
+    return xdr.OperationResult(xdr.OperationResultCode.opINNER, tr=tr)
+
+
+def _op_failure_results(operations: list[Operation]) -> list[xdr.OperationResult]:
+    """The per-operation results for a failed (stuck) transaction."""
+    if len(operations) == 1 and isinstance(operations[0], InvokeHostFunction):
+        tr = xdr.OperationResultTr(
+            xdr.OperationType.INVOKE_HOST_FUNCTION,
+            invoke_host_function_result=xdr.InvokeHostFunctionResult(
+                xdr.InvokeHostFunctionResultCode.INVOKE_HOST_FUNCTION_TRAPPED
+            ),
+        )
+        return [xdr.OperationResult(xdr.OperationResultCode.opINNER, tr=tr)]
+    return []