refactor: improve clarity and formatting in Result Callback guide

Author: Le-Caignec

src/guides/build-iapp/advanced/result-callback.md

@@ -1,114 +1,95 @@
 ---
 title: Result Callback Guide
-description: Guide to using the iExec result callback to push an off-chain iApp task result directly into a smart contract (price feeds, automation, triggers, proofs, scoring, etc.).
+description:
+  Guide to using the iExec result callback to push an off-chain iApp task result
+  directly into a smart contract (price feeds, automation, triggers, proofs,
+  scoring, etc.).
 ---
 
 # Result Callback
 
-This guide explains how to securely push an iExec task result into a smart contract using the callback mechanism.  
-Oracles are only one of many possible use cases.
-
-## When to Use a Callback
-
+This guide explains how to securely push an iExec task result into a smart
+contract using the callback mechanism.  
 Use a callback when a smart contract should:
 
-- Ingest off-chain computed data (API aggregation, ML inference, analytics) and persist it on-chain
+- Ingest off-chain computed data (API aggregation, ML inference, analytics) and
+  persist it on-chain
 - React to an execution outcome (conditional trigger, state transition)
 - Store a timestamped record (price feed, score, KPI, proof hash)
 - Act as a logic bridge between external systems and on-chain logic
 
 ## 🧩 High-Level Flow
 
 1. A requester executes an iApp on iExec.
-2. The iApp writes `${IEXEC_OUT}/computed.json` with a `callback-data` field containing ABI‑encoded calldata.
-3. The iExec protocol, once the task is completed, invokes the specified callback contract with that data.
+2. The iApp writes `${IEXEC_OUT}/computed.json` with a `callback-data` field
+   containing ABI‑encoded calldata.
+3. The iExec protocol, once the task is completed, invokes the specified
+   callback contract with that data.
 4. Your callback smart contract (receiver) ingests the data.
 
 ## Step-by-Step Implementation
 
 ### Step 1: Write the iApp
 
-The iApp MUST write a file named `computed.json` in the directory pointed to by `IEXEC_OUT`.  
-Required key: `callback-data` (raw ABI‑encoded bytes you want passed to your contract).
+The iApp MUST write a file named `computed.json` in the directory pointed to by
+`IEXEC_OUT`.  
+Required key: `callback-data` (raw ABI‑encoded bytes you want passed to your
+contract).
 
 Replaced Web3.js example with ethers v6:
 
-```js
-// ethers v6 example producing ABI-encoded callback data
-
+```ts twoslash
 import { writeFileSync } from 'node:fs';
 import { AbiCoder } from 'ethers';
 
-// Placeholder: replace with real price retrieval / aggregation logic
-async function fetchPrice(pair) {
-  // e.g. query multiple APIs, median, etc.
-  return 12345.6789;
-}
+const timestamp = Math.floor(Date.now() / 1000);
+const pair = 'BTC-USD';
+const scaled = '9';
+// ---cut---
 
 async function main() {
-  const [pair = 'BTC-USD', precision = '9'] = process.argv.slice(2);
-
-  const price = await fetchPrice(pair);
-  const scale = 10n ** BigInt(Number(precision));
-  const scaled = BigInt(Math.round(price * Number(scale)));
-
-  const timestamp = Math.floor(Date.now() / 1000);
+  // Your business logic here
 
   const abiCoder = new AbiCoder();
   const abiPayload = abiCoder.encode(
     ['uint256', 'string', 'uint256'],
-    [timestamp, `${pair}-${precision}`, scaled]
+    [timestamp, `${pair}`, scaled]
   );
 
   writeFileSync(
     `${process.env.IEXEC_OUT}/computed.json`,
-    JSON.stringify(
-      {
-        'callback-data': abiPayload,
-        metadata: {
-          pair,
-          precision,
-          timestamp,
-        }
-      }
-    )
+    JSON.stringify({
+      'callback-data': abiPayload,
+    })
   );
 }
-
-main().catch(() => process.exit(1));
 ```
 
 ### Step 2: Deploy the Callback Contract
 
-The callback contract receives and processes the off-chain result.  
-It can read the stored `resultsCallback` from the iExec hub (or proxy) to independently verify the task state.
+The callback contract receives and processes the off-chain result. Your contract
+must implement `receiveResult(bytes32,bytes)`interface from
+[ERC1154](https://github.com/iExecBlockchainComputing/iexec-solidity/blob/master/contracts/ERC1154/IERC1154.sol)
 
 ```solidity
-interface IIexecProxy {
-    struct Task {
-        uint256 status;
-        bytes   resultsCallback; // raw callback-data bytes
-        // ...existing fields...
-    }
-    function viewTask(bytes32 _id) external view returns (Task memory);
-}
-
-abstract contract IExecCallbackReceiver {
-    IIexecProxy public immutable iexec;
-    constructor(address _iexec) { iexec = IIexecProxy(_iexec); }
-
-    function _getCallback(bytes32 taskid) internal view returns (bytes memory) {
-        IIexecProxy.Task memory t = iexec.viewTask(taskid);
-        require(t.status == 3, "task-not-completed"); // 3 = COMPLETED (example)
-        return t.resultsCallback;
+contract IExecCallbackReceiver {
+    // ERC1154 - Callback processing
+    function receiveResult(bytes32 _callID, bytes memory callback) external {
+        // Parse results
+        (uint256 timestamp, string memory pairAndPrecision, uint256 scaledValue) =
+            abi.decode(callback, (uint256, string, uint256));
+
+        ...business logic...
     }
 }
 ```
 
 ### Step 3: Run the iApp with Callback
 
-When requesting the execution, set the callback contract address in the deal (or order) parameters.  
-After completion, the protocol calls your contract passing the `callback-data` bytes.
+When requesting the execution, set the callback contract address in the deal (or
+order) parameters.  
+After completion, the protocol calls your contract passing the `callback-data`
+bytes.
 
 Checklist:
 
@@ -118,11 +99,11 @@ Checklist:
 
 ## 🔄 Other Use Cases
 
-| Use Case | Description |
-|----------|-------------|
-| Price oracle | Multi-source API aggregation |
+| Use Case             | Description                              |
+| -------------------- | ---------------------------------------- |
+| Price oracle         | Multi-source API aggregation             |
 | Reputation / scoring | Off-chain ML / analytics pushed on-chain |
-| Audit hash | Security scan or verification artifact |
-| Automation | Workflow step completion signal |
-| Dynamic parameters | Adjust rates / thresholds / quorums |
-| Logical bridge | Sync external (IoT / legacy) state |
+| Audit hash           | Security scan or verification artifact   |
+| Automation           | Workflow step completion signal          |
+| Dynamic parameters   | Adjust rates / thresholds / quorums      |
+| Logical bridge       | Sync external (IoT / legacy) state       |