localharness 0.36.0

A Rust-native agent SDK with pluggable LLM backends (Gemini today). Streaming, custom tools, safety policies, background triggers — zero external binaries.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
#[allow(unused_imports)]
use crate::*;

// ---- tba (token-bound account: make YOUR agent's wallet EXECUTE a call) ------
//
// Every identity NFT has a deterministic token-bound account (ERC-6551
// `MultiSignerAccount`) — a smart wallet the NFT holder controls. This command
// lets an agent ACT through it from a shell, with no browser tab: deploy it,
// see its `$LH`, and make it EXECUTE an arbitrary call (a `$LH` transfer, or
// any `to` + `--data <hex>`).
// Authorization is enforced on-chain by the account (only the NFT holder or an
// enrolled signer can `execute`); the embedded sponsor pays the fee. Unblocks a
// guild's TBA voting in a parent DAO, an agent's TBA paying/calling, etc.
// Built on `registry::tba_execute_call_sponsored` / `tba_send_lh_sponsored` /
// `create_token_bound_account_sponsored`.

pub(crate) const TBA_USAGE: &str = "\
usage: localharness tba <show|deploy|exec> ...
  tba show   [--as <me>] [<name>]            your (or <name>'s) TBA address, $LH, deployed?
  tba deploy [--as <me>] [<name>]            deploy the TBA on-chain (createTokenBoundAccount)
  tba exec   [--as <me>] [--tba <name-or-0xaddr>] <to> <amount> [--data <hex>]
                                             make a TBA execute a call:
                                               no --data → send <amount> $LH to <to>
                                               --data <hex> → call <to> with <hex>, <amount> as value
                                               --tba → act through an owned TBA other than
                                                       your main (a guild's wallet, etc.); default
                                                       is your main TBA. The chain gates execute to
                                                       the TBA owner, so it must be one you control.
  <to> is a name (→ its on-chain owner) or a 0x… address.
  <amount> is in $LH (the transfer amount, or the ETH value forwarded with --data).";

pub(crate) async fn tba(caller: Option<&str>, rest: &[String]) -> i32 {
    match rest.first().map(String::as_str) {
        Some("show") => tba_show(caller, rest.get(1).map(String::as_str)).await,
        Some("deploy") => tba_deploy(caller, rest.get(1).map(String::as_str)).await,
        Some("exec") => tba_exec(caller, &rest[1..]).await,
        _ => {
            eprintln!("{TBA_USAGE}");
            2
        }
    }
}

/// Resolve the tokenId to operate on: an explicit `<name>` if given (it must be
/// registered), else the caller's OWN identity (`resolve_own_token_id` — MAIN,
/// or sole holding). Returns `(token_id, label)` where `label` is for display.
pub(crate) async fn tba_target_token(
    caller: Option<&str>,
    name: Option<&str>,
    signer: &k256::ecdsa::SigningKey,
) -> Result<(u64, String), String> {
    if let Some(n) = name {
        match registry::id_of_name(n).await {
            Ok(0) => Err(format!("tba: '{n}' is not registered")),
            Ok(id) => Ok((id, n.to_string())),
            Err(e) => Err(format!("tba: RPC error resolving '{n}': {e}")),
        }
    } else {
        let id = resolve_own_token_id(caller, signer).await?;
        let label = registry::name_of_id(id).await.unwrap_or_else(|_| format!("token #{id}"));
        Ok((id, label))
    }
}

/// `tba show [--as <me>] [<name>]` — print the token-bound account address, its
/// `$LH` balance, and whether it's deployed on-chain. Read-only, no `$LH` spent.
/// With an explicit `<name>` it's a PURE read (no local identity key needed —
/// you can inspect any agent's wallet); without one it resolves YOUR identity,
/// which requires a local key.
pub(crate) async fn tba_show(caller: Option<&str>, name: Option<&str>) -> i32 {
    let (token_id, label) = if let Some(n) = name {
        // Explicit name → pure on-chain read, no key required.
        match registry::id_of_name(n).await {
            Ok(0) => {
                eprintln!("tba show: '{n}' is not registered");
                return 1;
            }
            Ok(id) => (id, n.to_string()),
            Err(e) => {
                eprintln!("tba show: RPC error resolving '{n}': {e}");
                return 1;
            }
        }
    } else {
        // No name → resolve the caller's OWN identity (needs a local key).
        let signer = match load_signer(caller) {
            Ok(s) => s,
            Err(code) => return code,
        };
        match tba_target_token(caller, None, &signer).await {
            Ok(t) => t,
            Err(e) => {
                eprintln!("{e}");
                return 1;
            }
        }
    };
    let tba_addr = match registry::tba_of_token_id(token_id).await {
        Ok(Some(a)) => a,
        Ok(None) => {
            eprintln!("tba show: no token-bound account for '{label}' (token #{token_id})");
            return 1;
        }
        Err(e) => {
            eprintln!("tba show: RPC error: {e}");
            return 1;
        }
    };
    let balance = registry::token_balance_of(&tba_addr).await.unwrap_or(0);
    let deployed = registry::is_contract_deployed(&tba_addr).await.unwrap_or(false);
    println!("{label}  (token #{token_id})");
    println!("  wallet (TBA):  {tba_addr}");
    println!("  balance:       {}", fmt_lh(balance));
    println!(
        "  deployed:      {}",
        if deployed { "yes" } else { "no — run `tba deploy` before it can execute" }
    );
    0
}

/// `tba deploy [--as <me>] [<name>]` — deploy the token-bound account on-chain
/// via `createTokenBoundAccount` (idempotent; a no-op if already deployed).
/// Needed before the TBA can `execute` / hold signers. Sponsored gas.
pub(crate) async fn tba_deploy(caller: Option<&str>, name: Option<&str>) -> i32 {
    let (signer, sponsor) = match load_signer_and_sponsor(caller) {
        Ok(pair) => pair,
        Err(code) => return code,
    };
    let (token_id, label) = match tba_target_token(caller, name, &signer).await {
        Ok(t) => t,
        Err(e) => {
            eprintln!("{e}");
            return 1;
        }
    };
    let tba_addr = match registry::tba_of_token_id(token_id).await {
        Ok(Some(a)) => a,
        Ok(None) => {
            eprintln!("tba deploy: no token-bound account for '{label}' (token #{token_id})");
            return 1;
        }
        Err(e) => {
            eprintln!("tba deploy: RPC error: {e}");
            return 1;
        }
    };
    if registry::is_contract_deployed(&tba_addr).await.unwrap_or(false) {
        println!("{label}'s TBA {tba_addr} is already deployed — nothing to do.");
        return 0;
    }
    println!("deploying {label}'s TBA {tba_addr}");
    match registry::create_token_bound_account_sponsored(
        &signer,
        &sponsor,
        token_id,
        registry::ALPHA_USD_ADDRESS,
    )
    .await
    {
        Ok(tx) => {
            println!("✓ deployed  tx: {tx}");
            0
        }
        Err(e) => {
            eprintln!("tba deploy failed: {e}");
            1
        }
    }
}

/// `tba exec [--as <me>] [--tba <name-or-0xaddr>] <to> <amount> [--data <hex>]` —
/// make a token-bound account EXECUTE a call. With no `--data` this is a plain
/// `$LH` transfer of `<amount>` to `<to>` (`execute($LH, 0, transfer(to,
/// amount))`); with `--data <hex>` it calls `<to>` with that calldata and
/// forwards `<amount>` as the call value (`execute(to, amount, data)`). `<to>`
/// is a name (resolved to its on-chain owner address) or a raw `0x…` address.
/// The acting TBA defaults to the CALLER'S OWN main; `--tba` overrides it with
/// any TBA the caller controls — a name (→ `tokenBoundAccountByName`) or a raw
/// `0x…` address — so a GUILD's wallet can act (e.g. join + vote in a parent
/// guild's DAO). The MultiSignerAccount gates `execute` to the TBA owner
/// on-chain (`_isAuthorized`); a client-side owner check warns early for a name
/// target. The TBA is deployed first if needed (when its token id is known).
pub(crate) async fn tba_exec(caller: Option<&str>, rest: &[String]) -> i32 {
    // Pull an optional `--tba <name-or-0xaddr>` (override the acting TBA) and an
    // optional `--data <hex>` from anywhere in the args.
    let (tba_flag, after_tba) = match take_tba_flag(rest) {
        Ok(v) => v,
        Err(e) => {
            eprintln!("{e}");
            return 2;
        }
    };
    let (data_hex, positional) = match take_data_flag(&after_tba) {
        Ok(v) => v,
        Err(e) => {
            eprintln!("{e}");
            return 2;
        }
    };
    if positional.len() != 2 {
        eprintln!("{TBA_USAGE}");
        return 2;
    }
    let to_arg = &positional[0];
    let amount_arg = &positional[1];

    // Resolve `<to>`: a 0x address, or a name → its on-chain OWNER.
    use localharness::encoding::{classify_recipient, Recipient};
    let to_hex = match classify_recipient(to_arg) {
        Ok(Recipient::Address(a)) => a,
        Ok(Recipient::Name(n)) => match registry::owner_of_name(&n).await {
            Ok(Some(o)) => o,
            Ok(None) => {
                eprintln!("tba exec: '{n}' is not registered");
                return 1;
            }
            Err(e) => {
                eprintln!("tba exec: RPC error resolving '{n}': {e}");
                return 1;
            }
        },
        Err(e) => {
            eprintln!("tba exec: {e}");
            return 2;
        }
    };

    // `<amount>` is the $LH transfer amount (no --data) or the ETH call value.
    let amount_wei = match localharness::encoding::parse_token_amount(amount_arg) {
        Some(w) => w,
        None => {
            eprintln!("tba exec: invalid amount '{amount_arg}' (expected a number of $LH)");
            return 2;
        }
    };
    // The transfer path needs a positive amount; the --data path may forward 0.
    if data_hex.is_none() && amount_wei == 0 {
        eprintln!("tba exec: amount must be greater than 0 for a $LH transfer");
        return 2;
    }

    // Decode `--data <hex>` (0x-optional) when present.
    let data = match &data_hex {
        Some(h) => match decode_hex_arg(h) {
            Ok(b) => Some(b),
            Err(e) => {
                eprintln!("tba exec: {e}");
                return 2;
            }
        },
        None => None,
    };

    let (signer, sponsor) = match load_signer_and_sponsor(caller) {
        Ok(pair) => pair,
        Err(code) => return code,
    };
    let caller_addr = bytes_to_hex_str(&wallet::address(&signer));

    // Resolve the ACTING TBA. Default (no --tba) = the caller's OWN main TBA, as
    // before. With --tba it's an arbitrary owned TBA: a name → its
    // `tokenBoundAccountByName`, or a raw 0x address. The MultiSignerAccount gates
    // `execute` to the TBA owner on-chain (`_isAuthorized`), so signing as the
    // caller only works for a TBA the caller controls — the client check below is
    // a clean early warning, the chain is the real gate. `exec_token_id` is the id
    // backing the TBA when known (a name target / the caller's own), used to
    // auto-deploy a counterfactual TBA; `None` for a raw-address target (no
    // reverse index → we can't deploy it, only warn).
    let (tba_addr, exec_token_id, tba_label) = match &tba_flag {
        // --tba <name-or-0xaddr>: an explicit, possibly-foreign-but-owned TBA.
        Some(target) => {
            use localharness::encoding::{classify_recipient, Recipient};
            match classify_recipient(target) {
                Ok(Recipient::Address(a)) => {
                    // Raw TBA address — no on-chain reverse index to its token, so
                    // we can't resolve the controlling owner or auto-deploy. The
                    // on-chain `_isAuthorized` is the real gate.
                    (a.clone(), None, a)
                }
                Ok(Recipient::Name(n)) => {
                    let addr = match registry::tba_of_name(&n).await {
                        Ok(Some(a)) => a,
                        Ok(None) => {
                            eprintln!("tba exec: '{n}' is not registered (no token-bound account)");
                            return 1;
                        }
                        Err(e) => {
                            eprintln!("tba exec: RPC error resolving '{n}': {e}");
                            return 1;
                        }
                    };
                    // Client-side owner check: warn (don't block) when the name's
                    // controlling NFT owner isn't the caller. The chain still gates.
                    match registry::owner_of_name(&n).await {
                        Ok(Some(o)) if o.eq_ignore_ascii_case(&caller_addr) => {}
                        Ok(Some(o)) => {
                            eprintln!(
                                "warning: '{n}' is controlled by {o}, not you ({caller_addr}) — \
                                 the TBA's on-chain _isAuthorized will reject this unless you're \
                                 an enrolled signer."
                            );
                        }
                        _ => {}
                    }
                    // The token id backs the auto-deploy of a counterfactual TBA.
                    let id = registry::id_of_name(&n).await.unwrap_or(0);
                    (addr, if id != 0 { Some(id) } else { None }, n)
                }
                Err(e) => {
                    eprintln!("tba exec: --tba {e}");
                    return 2;
                }
            }
        }
        // No --tba: the caller's OWN identity (the original, unchanged behaviour).
        None => {
            let token_id = match resolve_own_token_id(caller, &signer).await {
                Ok(id) => id,
                Err(e) => {
                    eprintln!("{e}");
                    return 1;
                }
            };
            match registry::tba_of_token_id(token_id).await {
                Ok(Some(a)) => (a, Some(token_id), "your".to_string()),
                Ok(None) => {
                    eprintln!("tba exec: no token-bound account for your token #{token_id}");
                    return 1;
                }
                Err(e) => {
                    eprintln!("tba exec: RPC error: {e}");
                    return 1;
                }
            }
        }
    };

    // The TBA must be deployed before it can execute. Deploy first if we know its
    // token id (caller's own, or a name target). A raw-address target can't be
    // deployed (no token id) — surface a clean error instead of an opaque revert.
    if !registry::is_contract_deployed(&tba_addr).await.unwrap_or(false) {
        match exec_token_id {
            Some(token_id) => {
                println!("{tba_label} TBA {tba_addr} isn't deployed yet — deploying first …");
                if let Err(e) = registry::create_token_bound_account_sponsored(
                    &signer,
                    &sponsor,
                    token_id,
                    registry::ALPHA_USD_ADDRESS,
                )
                .await
                {
                    eprintln!("tba exec: TBA deploy failed: {e}");
                    return 1;
                }
            }
            None => {
                eprintln!(
                    "tba exec: TBA {tba_addr} isn't deployed and was given as a raw address \
                     (no token id to deploy it) — pass `--tba <name>` so it can be deployed, \
                     or deploy it first with `tba deploy`."
                );
                return 1;
            }
        }
    }

    let result = match &data {
        // Arbitrary call: execute(to, amount_as_value, data).
        Some(bytes) => {
            println!(
                "{tba_label} TBA {tba_addr} → execute({to_hex}, value {}, {} bytes of calldata) …",
                fmt_lh(amount_wei),
                bytes.len()
            );
            registry::tba_execute_call_sponsored(
                &signer,
                &sponsor,
                &tba_addr,
                &to_hex,
                amount_wei,
                bytes,
                registry::ALPHA_USD_ADDRESS,
            )
            .await
        }
        // Plain $LH transfer: execute($LH, 0, transfer(to, amount)).
        None => {
            println!("{tba_label} TBA {tba_addr} → send {} $LH to {to_hex}", fmt_lh(amount_wei));
            registry::tba_send_lh_sponsored(
                &signer,
                &sponsor,
                &tba_addr,
                &to_hex,
                amount_wei,
                registry::ALPHA_USD_ADDRESS,
            )
            .await
        }
    };
    match result {
        Ok(tx) => {
            println!("✓ executed  tx: {tx}");
            0
        }
        Err(e) => {
            eprintln!("tba exec failed: {e}");
            1
        }
    }
}