Yield & resume (NEP-519)

block N        alice -> oracle.near::ask("q")         converted to a receipt
block N+1      ask: store request #7 with its yield id; return the yielded promise
               alice's transaction is now WAITING; nothing else is blocked
               ... worker polls the pending() view or an indexer, computes "42" ...
block N+k      worker -> oracle.near::answer(7, "42")   YieldId::resume(payload) -> Ok
shortly after  on_answer(7) runs with Ok("42")          alice's tx result: "42"

# nobody answers?
block N+1+200  on_answer(7) runs with Err(PromiseError) timeout: refund, clean up

use near_sdk::store::IterableMap;
use near_sdk::{
    env, log, near, require, serde_json, AccountId, Gas, GasWeight, NearToken, PanicOnDefault,
    Promise, PromiseError, YieldId,
};

const GAS_FOR_ON_ANSWER: Gas = Gas::from_tgas(10);
const FEE: NearToken = NearToken::from_millinear(10);
const MAX_LEN: usize = 256;

#[near(serializers = [borsh, json])]
#[derive(Clone)]
pub struct Request {
    pub asker: AccountId,
    pub question: String,
    pub yield_id: YieldId, // JSON: base64 string, so workers can read it from a view
    pub fee: NearToken,
}

#[near(contract_state)]
#[derive(PanicOnDefault)]
pub struct Oracle {
    worker: AccountId,
    next_id: u64,
    requests: IterableMap<u64, Request>,
}

#[near]
impl Oracle {
    #[init]
    pub fn new(worker: AccountId) -> Self {
        Self { worker, next_id: 0, requests: IterableMap::new(b"r") }
    }

    #[payable]
    pub fn ask(&mut self, question: String) -> Promise {
        require!(question.len() <= MAX_LEN, "question too long");
        require!(env::attached_deposit() == FEE, "attach exactly 0.01 NEAR");
        let id = self.next_id;
        self.next_id += 1;

        // on_answer will be called with these args + the resume payload
        let args = serde_json::json!({ "request_id": id }).to_string();
        let (promise, yield_id) =
            Promise::new_yield("on_answer", args, GAS_FOR_ON_ANSWER, GasWeight(0));

        self.requests.insert(id, Request {
            asker: env::predecessor_account_id(),
            question,
            yield_id,
            fee: FEE,
        });
        // returning it makes on_answer's return value this transaction's result
        promise
    }

    /// For the worker: what is waiting?
    pub fn pending(&self, from_index: u32, limit: u32) -> Vec<(u64, Request)> {
        self.requests
            .iter()
            .skip(from_index as usize)
            .take(limit.min(50) as usize)
            .map(|(id, r)| (*id, r.clone()))
            .collect()
    }

    /// Called by the worker in its own transaction.
    pub fn answer(&mut self, request_id: u64, answer: String) {
        require!(env::predecessor_account_id() == self.worker, "only the worker may answer");
        require!(answer.len() <= MAX_LEN, "answer too long");
        let req = self
            .requests
            .get(&request_id)
            .unwrap_or_else(|| env::panic_str("unknown or finished request"));
        let payload = serde_json::to_vec(&answer).unwrap();
        req.yield_id
            .resume(payload)
            .unwrap_or_else(|_| env::panic_str("request is no longer waiting"));
    }

    /// Runs once: after resume, or after the 200-block timeout.
    #[private]
    pub fn on_answer(
        &mut self,
        request_id: u64,
        #[callback_result] answer: Result<String, PromiseError>,
    ) -> Option<String> {
        // always remove the request, on every branch
        let Some(req) = self.requests.remove(&request_id) else {
            return None;
        };
        match answer {
            Ok(a) => {
                Promise::new(self.worker.clone()).transfer(req.fee).detach();
                Some(a)
            }
            Err(_) => {
                log!("request {} timed out; refunding {}", request_id, req.asker);
                Promise::new(req.asker).transfer(req.fee).detach();
                None
            }
        }
    }
}