@parity/truapi-provider 0.1.1-dev-20260731.0 → 0.1.1-dev-20260814.0

package/README.md

@@ -2,15 +2,14 @@
 
 Network transport for the TrUAPI `ChainProvider` contract: an embedded
 [smoldot](https://github.com/smol-dot/smoldot) light client, or a remote
-WebSocket JSON-RPC node, behind one API. This is the WebAssembly build, for
-browser and desktop (webview) hosts. Android and iOS hosts use the same Rust
-crate natively over UniFFI, so network access works the same everywhere.
+WebSocket JSON-RPC node, behind one API. This package is the WebAssembly build,
+for browser and desktop (webview) hosts.
 
 You connect to a network by its genesis hash, and everything else is handled for
 you: the bundled catalog provides the spec and relay wiring, so clients never
 ship or refresh specs of their own. One light client is shared across all
-connections, and its synced state is saved between runs, so the next launch
-resumes where it left off instead of syncing from scratch.
+connections. Its synced state can be captured and restored, so a launch resumes
+from finalized state instead of syncing from scratch.
 
 ## Usage
 
@@ -29,45 +28,34 @@ import wasmUrl from "@parity/truapi-provider/truapi_provider_bg.wasm?url";
 
 await init({ module_or_path: wasmUrl });
 
-const provider = new ChainProviderBuilder().build();
-const connection = await provider.connect("0x77af…"); // genesis hash
+const genesis = "0x3740…";
+const builder = new ChainProviderBuilder();
+
+// Resume from the state saved by the previous run, when there is one.
+const saved = localStorage.getItem(`chain-db:${genesis}`);
+if (saved) builder.setDatabase(genesis, saved);
+
+const provider = builder.build();
+const connection = await provider.connect(genesis);
 
 connection.send('{"jsonrpc":"2.0","id":1,"method":"chainSpec_v1_genesisHash","params":[]}');
 const response = await connection.nextResponse(); // undefined once closed
 connection.close();
-```
-
-#### Android (Kotlin)
-
-Native targets deliver responses to a listener instead of a pull loop, and take
-the genesis hash as 32 raw bytes.
 
-```kotlin
-val provider = ChainProvider()
-
-val connection = provider.connect(genesisHash, object : ChainMessageListener {
-    override fun onMessage(message: String) { /* JSON-RPC response */ }
-    override fun onClosed() {}
-})
-
-connection.send("""{"jsonrpc":"2.0","id":1,"method":"chainSpec_v1_genesisHash","params":[]}""")
-connection.close()
+// Later, once the light client has synced, save state for the next launch.
+localStorage.setItem(`chain-db:${genesis}`, await provider.snapshot(genesis));
 ```
 
-#### iOS (Swift)
+Warm start is driven by the host: call `snapshot()` once the light client has
+synced, persist the string, and hand it back through `setDatabase()` before
+`build()` on the next launch.
 
-```swift
-let provider = ChainProvider()
+## Native hosts
 
-final class Responses: ChainMessageListener {
-    func onMessage(message: String) { /* JSON-RPC response */ }
-    func onClosed() {}
-}
-
-let connection = try provider.connect(genesisHash: genesis, listener: Responses())
-connection.send(request: #"{"jsonrpc":"2.0","id":1,"method":"chainSpec_v1_genesisHash","params":[]}"#)
-connection.close()
-```
+Android and iOS do not consume this package. The same `truapi-provider` crate is
+published for them as its own artifacts over UniFFI — a `TrUAPIProvider` Swift
+package and a `truapi-provider-android` AAR — exposing the same `ChainProvider`
+contract with the same bundled catalog, so the wiring differs only in language.
 
 ## Building
 

package/dist/truapi_provider.d.ts

@@ -78,6 +78,12 @@ export class Connection {
     /**
      * Resolve with the next JSON-RPC response or notification, or
      * `undefined` once the connection is closed or dead.
+     *
+     * Calling this in a loop is not optional: it is the only thing that drains
+     * the connection. Frames queue until they are taken, and once the backlog
+     * reaches the connection's budget further [`send`](Connection::send) calls
+     * come back as JSON-RPC errors instead of being queued, so a caller that
+     * sends without reading eventually gets nothing but errors.
      */
     nextResponse(): Promise<string | undefined>;
     /**
@@ -144,12 +150,12 @@ export interface InitOutput {
     readonly networkchains_people: (a: number, b: number) => void;
     readonly networkchains_relay: (a: number, b: number) => void;
     readonly setLogLevel: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_12915: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_12917: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_3697: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_3697_2: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_3697_3: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_7073: (a: number, b: number) => void;
+    readonly __wasm_bindgen_func_elem_19082: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_19084: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_3717: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_3717_2: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_3717_3: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_7114: (a: number, b: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/dist/truapi_provider.js

@@ -221,6 +221,12 @@ export class Connection {
     /**
      * Resolve with the next JSON-RPC response or notification, or
      * `undefined` once the connection is closed or dead.
+     *
+     * Calling this in a loop is not optional: it is the only thing that drains
+     * the connection. Frames queue until they are taken, and once the backlog
+     * reaches the connection's budget further [`send`](Connection::send) calls
+     * come back as JSON-RPC errors instead of being queued, so a caller that
+     * sends without reading eventually gets nothing but errors.
      * @returns {Promise<string | undefined>}
      */
     nextResponse() {
@@ -472,7 +478,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_12917(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_19084(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -589,28 +595,28 @@ function __wbg_get_imports() {
             console.warn(getObject(arg0));
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 979, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_12915);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 1825, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_19082);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
             // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("CloseEvent")], shim_idx: 20, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_3697);
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_3717);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000003: function(arg0, arg1) {
             // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("Event")], shim_idx: 20, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_3697_2);
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_3717_2);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000004: function(arg0, arg1) {
             // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("MessageEvent")], shim_idx: 20, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_3697_3);
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_3717_3);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000005: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [], shim_idx: 672, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_7073);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [], shim_idx: 675, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_7114);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000006: function(arg0, arg1) {
@@ -637,26 +643,26 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_7073(arg0, arg1) {
-    wasm.__wasm_bindgen_func_elem_7073(arg0, arg1);
+function __wasm_bindgen_func_elem_7114(arg0, arg1) {
+    wasm.__wasm_bindgen_func_elem_7114(arg0, arg1);
 }
 
-function __wasm_bindgen_func_elem_3697(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_3697(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_3717(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_3717(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_3697_2(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_3697_2(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_3717_2(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_3717_2(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_3697_3(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_3697_3(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_3717_3(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_3717_3(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_12915(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_19082(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_12915(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_19082(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -667,8 +673,8 @@ function __wasm_bindgen_func_elem_12915(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_12917(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_12917(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_19084(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_19084(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 

package/dist/truapi_provider_bg.wasm.d.ts

@@ -21,12 +21,12 @@ export const networkchains_bulletin: (a: number, b: number) => void;
 export const networkchains_people: (a: number, b: number) => void;
 export const networkchains_relay: (a: number, b: number) => void;
 export const setLogLevel: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_12915: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_12917: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_3697: (a: number, b: number, c: number) => void;
-export const __wasm_bindgen_func_elem_3697_2: (a: number, b: number, c: number) => void;
-export const __wasm_bindgen_func_elem_3697_3: (a: number, b: number, c: number) => void;
-export const __wasm_bindgen_func_elem_7073: (a: number, b: number) => void;
+export const __wasm_bindgen_func_elem_19082: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_19084: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_3717: (a: number, b: number, c: number) => void;
+export const __wasm_bindgen_func_elem_3717_2: (a: number, b: number, c: number) => void;
+export const __wasm_bindgen_func_elem_3717_3: (a: number, b: number, c: number) => void;
+export const __wasm_bindgen_func_elem_7114: (a: number, b: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity/truapi-provider",
-  "version": "0.1.1-dev-20260731.0",
+  "version": "0.1.1-dev-20260814.0",
   "description": "Network provider backends for the TrUAPI ChainProvider: an embedded smoldot light client and remote WebSocket JSON-RPC nodes, compiled to WebAssembly for browser hosts",
   "license": "MIT AND Apache-2.0",
   "author": "Parity Technologies <admin@parity.io>",