Bobine Contract Caller

Default entrypoint: scripts/call_bobine.mjs.

Upstream references

• Concept overview: \x3Chttps://www.bobine.tech/>
• Bobine project: \x3Chttps://github.com/hazae41/bobine>
• Standard libraries for Bobine WebAssembly VM: \x3Chttps://github.com/hazae41/stdbob>

Scope

• Calling a Bobine module through /api/execute
• Preparing typed Bobine params for contract methods
• Generating Ed25519 keys for Bobine auth sessions
• Performing an authenticated ed25519 call with nonce handling and signature

Runtime requirements

• Node.js 20+
• Network access to a Bobine server

Load on demand

• Read references/params.md only when params use packed arrays or quoted text: payloads
• Read references/runtime.md only when spark handling, outputs, or failure modes are unclear
• Use scripts/keygen.mjs only when the call needs ed25519 auth
• Use scripts/call_bobine.mjs for all unsigned and signed calls

Quick workflow

1. Use scripts/call_bobine.mjs as the default entrypoint for Bobine interactions.

2. Read references/params.md only if params are nested, packed, or need quoted text:.

3. Generate keys if the call needs ed25519 auth:

   node ./scripts/keygen.mjs
   

4. Call the target contract with explicit arguments:

   node ./scripts/call_bobine.mjs \
     --server http://localhost:8080 \
     --module \x3Ctarget-module> \
     --method \x3Ctarget-method> \
     --param text:Alice
   

Inputs

• call_bobine.mjs
  • --server: Bobine server base URL
  • --module: target module address
  • --method: target method name
  • --param: repeat once per typed param
  • --auth-module: optional deployed ed25519 auth module address
  • --sigkey: required when --auth-module is provided
  • --pubkey: required when --auth-module is provided
  • --spark-hex: optional one-off spark value for this exact call
  • --spark-effort: optional inline spark generation target

Param rules

• Scalars:
  • null
  • blob:\x3Chex>
  • bigint:\x3Cvalue>
  • number:\x3Cvalue>
  • text:\x3Cvalue>
• Arrays:
  • pack:[...]
  • array:[...]
• Nesting is allowed
• Quote the whole shell argument when it contains brackets, commas, or spaces
• Quote the text: payload itself when it contains , or ], for example text:"a,b]"

Gotchas

• --param is one top-level Bobine param per flag; nested arrays stay inside a single typed param string
• text: values containing , or ] must quote the payload itself, for example text:"a,b]"
• Signed calls require all of --auth-module, --sigkey, and --pubkey
• --spark-hex is a one-off override for a specific call; prefer --spark-effort when you want a fresh spark
• keygen.mjs prints secret material, so do not paste its output back to the user unless they explicitly ask for it

Signed call behavior

1. Read --server, target module, target method, and typed params
2. Build the Bobine session payload [auth_module, pubkey]
3. Derive the session address from sha256(pack(session))
4. Query \x3Cauth_module>.get_nonce(session_address)
5. Sign [domain, module, method, params, nonce]
6. Call \x3Cauth_module>.call(module, method, params, pubkey, signature)
7. Print a JSON object with logs, returned value, spark hex, and reported sparks

Output contract

• Scripts print a single JSON object on stdout on success
• Usage and failure diagnostics go to stderr
• Returned Bobine values are normalized into tagged JSON:
  • { "type": "text", "value": "hello" }
  • { "type": "bigint", "value": "42" }
  • { "type": "array", "value": [...] }
• keygen.mjs prints { "sigkey": "...", "pubkey": "..." }

Safety

• Do not echo private keys back to the user unless they explicitly ask for them
• Treat sigkey as sensitive
• Prefer a fresh inline spark by default; use --spark-hex only when you deliberately want to supply a one-off spark
• Surface server errors and decoded logs instead of retrying blindly

Troubleshooting

• Missing required call arguments: re-run with --server, --module, --method, and any required auth flags
• Unknown value type: read references/params.md
• Failed Bobine execute request: report the HTTP status and response body
• Invalid session or Unauthorized: the auth module, nonce, keys, or target contract assumptions are wrong