Merge pull request #2393 from oasisprotocol/uniyalabhishek/rofl-client-ts/queries-endpoint

feat: update rofl-client ts to include queries endpoint

Author: ptrus

docs/rofl/features/appd.md

@@ -110,7 +110,7 @@ Subcall.roflEnsureAuthorizedOrigin(roflAppID);
     "data": {
       "gas_limit": 200000,
       "to": "1234845aaB7b6CD88c7fAd9E9E1cf07638805b20",
-      "value": 0,
+      "value": "0",
       "data": "dae1ee1f00000000000000000000000000000000000000000000000000002695a9e649b2"
     }
   }
@@ -123,7 +123,9 @@ Subcall.roflEnsureAuthorizedOrigin(roflAppID);
   supported (as defined by the `kind` field):
 
   - Ethereum-compatible calls (`eth`) use standard fields (`gas_limit`, `to`,
-    `value` and `data`) to define the transaction content.
+    `value` and `data`) to define the transaction content. `value` must be a
+    decimal string (or `0x` hex string) representing a non-negative integer
+    up to 256 bits.
 
   - Oasis SDK calls (`std`) support CBOR-serialized hex-encoded `Transaction`s
     to be specified.

rofl-appd/src/routes/tx.rs

@@ -56,12 +56,48 @@ pub enum Transaction {
         gas_limit: u64,
         #[serde_as(as = "serde_with::hex::Hex")]
         to: Vec<u8>,
-        value: u128,
+        value: TransactionValue,
         #[serde_as(as = "serde_with::hex::Hex")]
         data: Vec<u8>,
     },
 }
 
+/// Value representation that accepts either a string (decimal or 0x hex) or a JSON number.
+#[derive(Clone, Debug, serde::Deserialize)]
+#[serde(untagged)]
+pub enum TransactionValue {
+    String(String),
+    Number(u128),
+}
+
+impl TransactionValue {
+    fn into_u256(self) -> Result<evm::types::U256, String> {
+        match self {
+            TransactionValue::Number(value) => Ok(value.into()),
+            TransactionValue::String(value) => parse_u256_string(value),
+        }
+    }
+}
+
+fn parse_u256_string(value: String) -> Result<evm::types::U256, String> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        return Err("transaction value string must not be empty".to_string());
+    }
+    let (radix, digits) = match trimmed
+        .strip_prefix("0x")
+        .or_else(|| trimmed.strip_prefix("0X"))
+    {
+        Some(rest) => (16, rest),
+        None => (10, trimmed),
+    };
+    if digits.is_empty() {
+        return Err("transaction value string must contain digits".to_string());
+    }
+    evm::types::U256::from_str_radix(digits, radix)
+        .map_err(|_| "transaction value string is not a valid unsigned integer".to_string())
+}
+
 /// Transaction signing and submission request.
 #[serde_as]
 #[derive(Clone, Debug, serde::Deserialize)]
@@ -115,12 +151,13 @@ pub async fn sign_and_submit(
             value,
             data,
         } => {
+            let value = value.into_u256().map_err(|err| (Status::BadRequest, err))?;
             let (method, body) = if to.is_empty() {
                 // Create.
                 (
                     "evm.Create",
                     cbor::to_value(evm::types::Create {
-                        value: value.into(),
+                        value,
                         init_code: data,
                     }),
                 )
@@ -135,7 +172,7 @@ pub async fn sign_and_submit(
                     "evm.Call",
                     cbor::to_value(evm::types::Call {
                         address,
-                        value: value.into(),
+                        value,
                         data,
                     }),
                 )
@@ -191,3 +228,43 @@ pub async fn sign_and_submit(
 
     Ok(Json(response))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::{evm, *};
+
+    #[test]
+    fn parse_u256_string_supports_decimal_and_hex() {
+        let decimal = parse_u256_string("42".to_string()).unwrap();
+        assert_eq!(decimal, evm::types::U256::from(42u32));
+
+        let hex_lower = parse_u256_string("0x2a".to_string()).unwrap();
+        assert_eq!(hex_lower, evm::types::U256::from(42u32));
+
+        let hex_upper = parse_u256_string("  0X2A  ".to_string()).unwrap();
+        assert_eq!(hex_upper, evm::types::U256::from(42u32));
+    }
+
+    #[test]
+    fn parse_u256_string_rejects_invalid_inputs() {
+        assert!(parse_u256_string("".to_string()).is_err());
+        assert!(parse_u256_string("0x".to_string()).is_err());
+        assert!(parse_u256_string("-1".to_string()).is_err());
+        assert!(parse_u256_string("0xZZ".to_string()).is_err());
+    }
+
+    #[test]
+    fn transaction_value_into_u256_handles_number_variant() {
+        let value = TransactionValue::Number(10u128.pow(18));
+        assert_eq!(
+            value.into_u256().unwrap(),
+            evm::types::U256::from(10u128.pow(18))
+        );
+    }
+
+    #[test]
+    fn transaction_value_into_u256_handles_string_variant() {
+        let value = TransactionValue::String("1000".to_string());
+        assert_eq!(value.into_u256().unwrap(), evm::types::U256::from(1000u32));
+    }
+}

rofl-client/ts/.prettierrc.js rofl-client/ts/.prettierrc.cjsrofl-client/ts/.prettierrc.js renamed to rofl-client/ts/.prettierrc.cjs

@@ -30,7 +30,7 @@ const callResultBytes = await client.signAndSubmit({
   kind: 'eth',
   gas_limit: 200_000,
   to: '',                    // empty => contract creation
-  value: 0,
+  value: '0',                // decimal or 0x hex string
   data: '0x',                // hex calldata (0x optional)
 });
 // `callResultBytes` is the raw CBOR-encoded CallResult (Uint8Array)
@@ -57,6 +57,11 @@ const callResultBytes = await client.signAndSubmit({
 - `getMetadata(): Promise<Record<string, string>>`
 - `setMetadata(metadata: Record<string, string>): Promise<void>`
 - `getAppId(): Promise<string>` (helper)
+- `query<TArgs = void, TResult = unknown>(method: string,
+  args?: QueryArgsInput<TArgs>): Promise<TResult)`
+  ([`QueryArgsInput`](#queryargsinput))
+  - Encodes `args` as CBOR (or uses provided binary CBOR), POSTs to
+    `/rofl/v1/query`, and decodes the CBOR response body into `TResult`.
 - `signAndSubmit(tx: StdTx | EthTx, opts?: { encrypt?: boolean }):
   Promise<Uint8Array>`
   - Signs the transaction with an app-authenticated key, submits it,
@@ -65,6 +70,39 @@ const callResultBytes = await client.signAndSubmit({
 
 [`CallResult`]: https://api.docs.oasis.io/rust/oasis_runtime_sdk/types/transaction/enum.CallResult.html
 
+### Runtime Queries
+
+`query` lets you execute read-only runtime methods exposed by ROFL-compatible
+paratimes. Use the generated types from `@oasisprotocol/client-rt` for complete
+type safety:
+
+```ts
+import {rofl, types} from '@oasisprotocol/client-rt';
+import {RoflClient} from '@oasisprotocol/rofl-client';
+
+const client = new RoflClient();
+const appConfig = await client.query<types.RoflAppQuery, types.RoflAppConfig>(
+  rofl.METHOD_APP,
+  { id: myAppId }
+);
+```
+
+If you already have CBOR-encoded arguments (e.g., from `oasis.misc.toCBOR`),
+pass them directly as `Uint8Array`, `Buffer`, `ArrayBuffer`, or any
+`ArrayBufferView` via `QueryArgsInput`.
+
+### QueryArgsInput
+
+`QueryArgsInput<TArgs>` mirrors the runtime schema expected by your query method:
+
+- When `TArgs` is anything other than `void`, you must pass either structured arguments (`TArgs`)
+  or pre-encoded CBOR bytes (`Uint8Array`, `Buffer`, `ArrayBuffer`, or any `ArrayBufferView`).
+- When `TArgs` is omitted or `void`, the `args` parameter becomes optional; omit it to send `null`
+  or pass CBOR bytes directly.
+
+This keeps the `query` call site type-safe—TypeScript now enforces that calls providing structured
+types also supply the corresponding payload.
+
 ### KeyKind
 
 Supported key generation types (serialized as stable strings):
@@ -88,8 +126,11 @@ type EthTx = {
   gas_limit: number;
   /** Hex address (0x optional). Empty string => contract creation. */
   to: string;
-  /** JSON number; must fit JS number range (backend expects u128). */
-  value: number;
+  /**
+   * Transaction value in wei. Accepts decimal strings, 0x-prefixed hex strings,
+   * bigint, or safe JS integers. Values are normalized to decimal strings.
+   */
+  value: string | number | bigint;
   /** Hex calldata (0x optional). */
   data: string;
 };

rofl-client/ts/README.md

@@ -23,12 +23,16 @@ async function main() {
         const appId = await client.getAppId();
         console.log('App ID:', appId);
 
+        // Read-only runtime query (no args -> CBOR null)
+        const runtimeInfo = await client.query('core.RuntimeInfo');
+        console.log('Runtime info:', runtimeInfo);
+
         // Sign & submit (ETH style)
         const result = await client.signAndSubmit({
             kind: 'eth',
             gas_limit: 200_000,
             to: '', // empty => contract creation
-            value: 0,
+            value: '0',
             data: '0x', // no-op calldata
         });
         console.log('CallResult (hex):', Buffer.from(result).toString('hex'));

rofl-client/ts/examples/basic_usage.ts

@@ -0,0 +1,11 @@
+module.exports = {
+    testMatch: ['**/test/**/*.ts'],
+    testEnvironment: 'node',
+    transform: {
+        '^.+\\.ts$': ['ts-jest', {tsconfig: 'tsconfig.test.json'}],
+    },
+    modulePathIgnorePatterns: ['<rootDir>/dist'],
+    moduleNameMapper: {
+        '^(\\.{1,2}/.*)\\.js$': '$1',
+    },
+};