From 85dd28b2414db6c0b6a72d4ecf5d0aa35f41cc24 Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Sat, 4 Apr 2026 18:49:31 -0300 Subject: update parameter passing protocol with presence byte (by @TheAwiteb). --- 5C.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/5C.md b/5C.md index dcf0d2c..37197e1 100644 --- a/5C.md +++ b/5C.md @@ -117,24 +117,38 @@ For example, this scroll could be displayed as an option to be clicked on any us ### Parameter Passing -When the host calls `run()`, it passes a single pointer to a buffer containing all parameters in the order they appear in the tags. Each type has a specific encoding: +When the host calls `run()`, it passes a single pointer to a buffer containing all parameters in the order they appear in the tags. Each type has a specific length or a way to determine its length (for strings, as described in "String Convention", this is a 4-byte prefix). -| Type | Encoding | Size | -| ------------ | --------------------------------------------------------------------- | ------------- | -| `public_key` | 32 bytes (should all be set to zero if the parameter is not provided) | 32 bytes | -| `event` | i32 handle | 4 bytes | -| `string` | u32_be length followed by UTF-8 bytes | 4 + len bytes | -| `number` | i32 | 4 bytes | -| `timestamp` | unix timestamp as u32_be | 4 bytes | -| `relay` | relay URL, same as string | 4 + len bytes | +The host must prefix every parameter with a single presence byte: `1` indicates the parameter is provided, and `0` indicates it is omitted. If a required parameter is prefixed with `0`, the program must panic. -For example: in a scroll with parameters `[me: public_key, target_event: event, target_relay: relay]` the buffer layout would be: +| Type | Encoding | Size (if provided) | +| ------------ | --------------------------------------------------------------------- | ------------------ | +| `public_key` | 32 bytes | 32 bytes | +| `event` | i32 handle | 4 bytes | +| `string` | u32_be length followed by UTF-8 bytes | 4 + len bytes | +| `number` | i32 | 4 bytes | +| `timestamp` | Unix timestamp as u32_be | 4 bytes | +| `relay` | Relay URL, same encoding as string | 4 + len bytes | + +For example, in a scroll with these parameters: + +```json +[ + ["param", "me", "", "public_key", "required"], + ["param", "note", "", "event", "required", "1,1111"], + ["param", "author", "", "public_key", ""], + ["param", "place", "", "relay", "required"] +] ``` -[ 32-byte current user pubkey ][ 4-byte i32 handle ][ 4-byte len for relay URL ][ UTF-8 relay URL ] + +The buffer layout would be: + +```text +[ 1 ][ 32-byte pubkey ][ 1 ][ 4-byte handle ][ 0 ][ 1 ][ 4-byte len ][ UTF-8 relay URL ] ``` -The WASM program reads this by iterating through the declared parameters in order, reading the appropriate number of bytes for each type. +Because `author` is optional and not provided, its position contains only the `0` presence byte. --- -- cgit v1.2.3