feat(fees): charge LLM tokens and permit deploy balance fees ✨

docs/website/src/impl-spec/03-greyboxing/index.rst

@@ -21,6 +21,18 @@ Retrieving Data from :term:`Host`
 Host can provide additional data to the :term:`Module` to help it make decisions,
 only transaction id and node address are required, as they are required for signing requests.
 
+Token Charges
+-------------
+
+The default Lua policy charges 1/4 time unit per 1,000 provider-reported total
+tokens, using the host's ``gas_data.genPerTimeUnit`` price. A model can override
+the rate with ``meta.time_units_per_1k_tokens``, a non-negative rational string
+such as ``"1/2"`` or ``"0"``. Invalid rates fail before calling that provider
+
+The charge is ``ceil(total_tokens * genPerTimeUnit * rate / 1000)`` in GEN-wei,
+computed with exact rational arithmetic. Missing or zero ``genPerTimeUnit``
+keeps the charge at zero
+
 Current Built-in Filters
 ------------------------
 

docs/website/src/spec/03-vm/02-meta-properties.rst

@@ -140,3 +140,5 @@ flag has no effect on ``EmitExternalMessage``.
 Unlike the meta-properties above, this one is stored as a bit in the root slot's
 inline ``permissions`` bitfield and read before execution begins. The bit offset
 is the corresponding member of :ref:`gvm-def-enum-permissions`.
+
+A deployment is the exception: permission is granted unconditionally.

docs/website/src/spec/04-contract-interface/03-storage.rst

@@ -61,7 +61,8 @@ the following data:
   the slot it points to (same 4-byte-length-prefixed layout). This lets a contract serve its
   code from an arbitrary slot, including one shared via a ``chain:<address>:<d|f>:<slot>`` runner id.
 - ``permissions``: (offset 37) A 32-byte (``u256``) little-endian permission bitfield read by
-  the executor at the start of every load. Bit ``n`` corresponds to the permission whose value
+  the executor at the start of every load but a deployment, which grants every permission in it
+  instead (see :ref:`gvm-perm-use-balance-for-message-fees`). Bit ``n`` corresponds to the permission whose value
   is ``n`` (currently only bit ``0``, ``can_use_balance_for_message_fees``). It is not reserved:
   contracts may set it (see ``Root.get_permission`` / ``Root.set_permission`` in the Python SDK).
 

implementation/tests/policy_dispatch.rs

@@ -98,17 +98,29 @@ fn build_config(
 ) -> (
     sync::DArc<config::Config>,
     Arc<BTreeMap<String, Box<dyn providers::Provider + Send + Sync>>>,
+) {
+    build_config_with_model_meta(backends, serde_json::Value::Null)
+}
+
+fn build_config_with_model_meta(
+    backends: &[(&FakeBackend, i64, bool)],
+    model_meta: serde_json::Value,
+) -> (
+    sync::DArc<config::Config>,
+    Arc<BTreeMap<String, Box<dyn providers::Provider + Send + Sync>>>,
 ) {
     let mut cfg_backends = BTreeMap::new();
     let mut provider_map = BTreeMap::new();
 
     for (fake, priority, supports_json) in backends {
+        let mut model = model_cfg(*supports_json);
+        model.meta = model_meta.clone();
         let backend = config::BackendConfig {
             enabled: true,
             provider: config::Provider::OpenaiCompatible,
             key: "<empty>".to_owned(),
             script_config: config::ScriptBackendConfig {
-                models: BTreeMap::from([("model".to_owned(), model_cfg(*supports_json))]),
+                models: BTreeMap::from([("model".to_owned(), model)]),
                 meta: serde_json::json!({ "priority": priority }),
                 timeout: None,
             },
@@ -163,10 +175,33 @@ async fn run_prompt(
     config: &sync::DArc<config::Config>,
     providers: Arc<BTreeMap<String, Box<dyn providers::Provider + Send + Sync>>>,
     format: llm_iface::OutputFormat,
+) -> anyhow::Result<String> {
+    run_priced_prompt(
+        config,
+        providers,
+        format,
+        None,
+        primitive_types::U256::zero(),
+    )
+    .await
+}
+
+async fn run_priced_prompt(
+    config: &sync::DArc<config::Config>,
+    providers: Arc<BTreeMap<String, Box<dyn providers::Provider + Send + Sync>>>,
+    format: llm_iface::OutputFormat,
+    time_unit_price: Option<&str>,
+    expected_charge: primitive_types::U256,
 ) -> anyhow::Result<String> {
     let user_vm = create_vm(config).await.unwrap();
 
-    let hello = common::tests::get_hello();
+    let mut hello = common::tests::get_hello();
+    if let Some(price) = time_unit_price {
+        Arc::get_mut(&mut hello)
+            .unwrap()
+            .gas_data
+            .insert("genPerTimeUnit".to_owned(), price.to_owned());
+    }
     let metrics = sync::DArc::new(Metrics::default());
     let scripting_ctx = scripting::create_ctx_part(
         &hello,
@@ -210,6 +245,10 @@ async fn run_prompt(
         .call_fn(&user_vm.data.exec_prompt, (ctx_lua, payload, fuel))
         .await?;
     let table = res.as_table().unwrap();
+    assert_eq!(
+        scripting::rat::lua_rat_to_u256(table).unwrap(),
+        expected_charge
+    );
     let data: llm_iface::PromptAnswerData =
         user_vm.vm.from_value(table.get("data").unwrap()).unwrap();
     match data {
@@ -218,6 +257,88 @@ async fn run_prompt(
     }
 }
 
+#[tokio::test]
+async fn token_charge_rounds_up_the_total_using_rational_prices() {
+    common::tests::setup();
+    let hits = Arc::new(Mutex::new(Vec::new()));
+    let backend = spawn_fake("priced", vec![200], hits);
+    let (config, providers) = build_config(&[(&backend, 0, true)]);
+
+    for (price, charge) in [
+        ("0", 0u64),
+        ("1", 1),
+        ("4000", 2),
+        ("4001", 3),
+        ("8001/2", 3),
+        ("9007199254742001", 4503599627372),
+    ] {
+        let answer = run_priced_prompt(
+            &config,
+            providers.clone(),
+            llm_iface::OutputFormat::Text,
+            Some(price),
+            primitive_types::U256::from(charge),
+        )
+        .await
+        .unwrap();
+        assert_eq!(answer, "ok");
+    }
+}
+
+#[tokio::test]
+async fn model_meta_overrides_the_token_rate() {
+    common::tests::setup();
+    let hits = Arc::new(Mutex::new(Vec::new()));
+    let backend = spawn_fake("priced", vec![200], hits);
+    for (rate, charge) in [("0", 0u64), ("1/2", 4)] {
+        let (config, providers) = build_config_with_model_meta(
+            &[(&backend, 0, true)],
+            serde_json::json!({ "time_units_per_1k_tokens": rate }),
+        );
+        let answer = run_priced_prompt(
+            &config,
+            providers,
+            llm_iface::OutputFormat::Text,
+            Some("4000"),
+            primitive_types::U256::from(charge),
+        )
+        .await
+        .unwrap();
+        assert_eq!(answer, "ok");
+    }
+}
+
+#[tokio::test]
+async fn invalid_token_rates_fail_before_calling_a_provider() {
+    common::tests::setup();
+    let hits = Arc::new(Mutex::new(Vec::new()));
+    let backend = spawn_fake("priced", vec![200], hits.clone());
+    for rate in [
+        serde_json::json!("-1/4"),
+        serde_json::json!("invalid"),
+        serde_json::json!(0.25),
+        serde_json::json!(false),
+    ] {
+        let (config, providers) = build_config_with_model_meta(
+            &[(&backend, 0, true)],
+            serde_json::json!({ "time_units_per_1k_tokens": rate }),
+        );
+        let error = run_prompt(&config, providers, llm_iface::OutputFormat::Text)
+            .await
+            .unwrap_err();
+        let message = format!("{error:#}");
+        assert!(
+            message.contains("time_units_per_1k_tokens")
+                || message.contains("failed to parse rational"),
+            "unexpected error: {message}"
+        );
+    }
+    assert!(
+        hits.lock().unwrap().is_empty(),
+        "invalid pricing must not call a provider"
+    );
+}
+
 // Higher priority is tried first; an overloaded provider falls through to the
 // next in priority order; the survivor's answer is returned.
 #[tokio::test]

install/config/genvm-llm-default.lua

@@ -8,16 +8,21 @@ local sqlite3 = require("lsqlite3")
 -- Instead, each genvm creates a session, which has a single `ctx` object,
 -- which is preserved across multiple calls
 
---- Gas (gen) charged per token for a given provider/model.
---- TODO: per-model pricing is not configured yet, so this always returns 0.
---- Once a price table exists, look up the gen-per-token rate here so that token
---- usage is converted into gen and charged to the host as fuel.
+--- GEN-wei charged per token, before rounding the total charge.
 ---@param ctx any execution context
 ---@param provider string provider id
 ---@param model string model name
----@return number|Rat gen charged per token
+---@return Rat GEN-wei charged per token
 local function gen_per_token(ctx, provider, model)
-	return rat.zero
+	local meta = llm.providers[provider].models[model].meta
+	local rate = meta and meta.time_units_per_1k_tokens
+	if rate == nil then
+		rate = "1/4"
+	end
+	assert(type(rate) == "string", "time_units_per_1k_tokens must be a rational string")
+	rate = rat.new(rate)
+	assert(rate >= rat.zero, "time_units_per_1k_tokens must be non-negative")
+	return (ctx.gen_per_time_unit or rat.zero) * rate / rat.new(1000)
 end
 
 local function get_or_create_stats(ctx, provider, model)
@@ -241,11 +246,12 @@ local function run_candidate(ctx, mapped_prompt, timeout, request)
 	}
 
 	lib.log { level = "trace", message = "calling exec_prompt_in_provider", request = call }
+	local token_price = gen_per_token(ctx, call.provider, call.model)
 	local success, result = pcall(exec_update_policy_data, ctx, call, function(res)
 		-- convert token usage into gen using the per-model rate, and report it
 		-- back as the gen consumed by this call (charged to the host as fuel)
 		local total_tokens = (res.tokens and res.tokens.total) or 0
-		local consumed_gen = rat.new(total_tokens) * gen_per_token(ctx, call.provider, call.model)
+		local consumed_gen = (rat.new(total_tokens) * token_price):ceil()
 		res.consumed_gen = consumed_gen
 		return consumed_gen
 	end)