Struct FrameBuilder 

pub struct FrameBuilder<'a> { /* private fields */ }

Builder for configuring and executing a single invocation frame.

Implementations

impl<'a> FrameBuilder<'a>

pub fn with_calldata(self, calldata: BytesM) -> FrameBuilder<'a>

Set the calldata the invoked frame observes (default: empty).

pub fn with_flags(self, flags: u32) -> FrameBuilder<'a>

Set the frame’s invoke flags, a bitset of InvokeFlag values (default: none).

pub fn run<T>(self, f: impl FnOnce() -> T + UnwindSafe) -> FrameResult

where T: WriteXDR,

Execute the frame with the given closure, then close it.

The closure’s return value is XDR-encoded into the frame’s return buffer (the same convention generated #[contract] entrypoints use), and can be recovered from the result via assert_return_as. Any value that encodes to zero bytes (e.g. ()) skips the explicit return and leaves the buffer untouched: an empty buffer is already the valid encoding of such types, so decoding them still works. Separately, closures that call raw_Return themselves never reach this encode step at all, since raw_Return terminates the invocation immediately (it never returns).

Mixing an explicit raw_Return with a non-unit closure return is unsupported; the explicit buffer wins and the closure’s value is never encoded.

The return buffer is subject to the protocol’s return-size cap (1024 bytes); a larger encoded value deterministically reverts the invocation, surfacing as an opaque frame failure. Keep test return values small — return a digest or summary instead of bulk data.

If you need to open child frames from within the closure, use run_continuable instead, which provides a FrameHandle with child_call().

pub fn run_continuable( self, f: impl FnOnce(&mut FrameHandle<'_>) -> FrameAction + UnwindSafe, ) -> ContinuableFrame<'a>

Execute the frame with a closure that receives a FrameHandle and returns a FrameAction. If FrameAction::Continue, returns a ContinuableFrame for further chaining.

To return a typed value from a continuable frame, end the closing step with an explicit raw_Return — it sets the buffer and diverges (closing the frame), and ! coerces to FrameAction:

let result = tx.call(&addr)
    .run_continuable(|frame| {
        // ... child calls, multi-step work ...
        raw_Return(&xdrs::cxs::encode(&value).unwrap(), false, &[])
    })
    .finish();
let v: T = result.assert_return_as();