windkit 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wind Stack | Vexanium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# WindKit
+A protocol to connect Vexanium DApps to the Wind wallet.
+
+## Features
+- Cross-device login via VSR (Vexanium Signing Request)
+- Transaction signing (single or multiple actions)
+- Message signing
+- Shared secret (ECDH) for encryption
+
+## Initialize the Connector
+```javascript
+import { WindConnector } from "windkit";
+
+const connector = new WindConnector();
+connector.on("session", onSession); // fires after wallet approves login
+await connector.connect();
+```
+
+## Create a Login Request and Open the Wallet
+```javascript
+// Build a VSR and deep-link / QR it to the wallet
+const vsr = connector.createLoginRequest("Vexanium DApp", "https://example.com/icon.png");
+const request = vsr.split(":")[1];
+
+// Open Wind Wallet login (adjust the URL/host as needed)
+const walletUrl = `https://windwallet.app/login?vsr=${request}`;
+window.open(walletUrl, "Wind Wallet");
+```
+
+## Receive a WalletSession
+```javascript
+import { ABICache } from "@wharfkit/abicache";
+
+const abiCache = new ABICache({/* optional custom fetch */});
+
+function onSession(session, proof) {
+  // Optional on first login: verify IdentityProof as needed
+  const account = proof?.signer?.toString?.(); // e.g., "userxyz@active"
+
+  session.setABICache(abiCache);  // faster ABI (de)serialization
+  session.onClose(() => console.log("Disconnected from wallet"));
+  
+  // Store for later use
+  Store.session = session;
+}
+```
+
+## Send a Transaction
+```javascript
+import { Action } from "@wharfkit/antelope";
+
+// Example: transfer VEX
+const abi = await abiCache.getAbi("vex.token");
+const data = {
+  from: "aiueo",
+  to: "babibu",
+  quantity: "1.0000 VEX",
+  memo: "test transfer"
+};
+
+const action = Action.from(
+  {
+    account: "vex.token",
+    name: "transfer",
+    data,
+    authorization: [Store.session.permissionLevel]
+  },
+  abi
+);
+
+// By default, transact() broadcasts. Set { broadcast: false } to sign only.
+const result = await Store.session.transact({ action });
+// result is either SendTransactionResponse (broadcast) or SignedTransaction (sign-only)
+console.log(result.transaction_id ?? result.id);
+```
+
+> Notes  
+> - Class names: `WindConnector` (connector) and `WalletSession` (active session).  
+> - Chain ID is handled internally by `WalletSession.ChainID` (Vexanium mainnet).  
+> - For re-login, the `session` event may be called without `proof` (use `session.permissionLevel`).  

package/index.js

@@ -0,0 +1,4 @@
+import { WindConnector } from "./src/WindConnector.js";
+import { WalletSession } from "./src/WalletSession.js";
+
+export { WindConnector, WalletSession };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "windkit",
+  "version": "0.1.1",
+  "description": "A protocol for connecting Vexanium DApps to the Wind wallet, enabling secure communication and transaction signing.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/windvex/windkit.git"
+  },
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "cryptocurrency",
+    "web3",
+    "dapp",
+    "walletconnect",
+    "windkit",
+    "web-rtc",
+    "peerjs",
+    "vexanium",
+    "vex",
+    "blockchain"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@wharfkit/abicache": "^1.2.2",
+    "@wharfkit/antelope": "^1.0.13",
+    "@wharfkit/signing-request": "^3.2.0",
+    "pako": "^2.1.0",
+    "peerjs": "^1.5.4"
+  }
+}

package/src/WalletSession.js

@@ -0,0 +1,246 @@
+import { SigningRequest } from "@wharfkit/signing-request";
+import {
+  Action,
+  Checksum512,
+  Name,
+  PermissionLevel,
+  PublicKey,
+  Signature,
+  SignedTransaction,
+  Transaction
+} from "@wharfkit/antelope";
+import { ABICache } from "@wharfkit/abicache";
+import zlib from "pako";
+
+export class WalletSession {
+  // Vexanium mainnet Chain ID (constant)
+  static ChainID = "f9f432b1851b5c179d2091a96f593aaed50ec7466b74f89301f957a83e56ce1f";
+
+  #connection;
+  #callbacks;
+  #encodingOptions;
+  /**
+   * @type {PermissionLevel}
+   */
+  #permissionLevel;
+  #closeListener;
+  #errorListener;
+
+  /**
+   * Wraps a DataConnection to communicate with the wallet.
+   * @param {import('peerjs').DataConnection} connection
+   */
+  constructor(connection) {
+    this.#connection = connection;
+    this.#callbacks = new Map();
+
+    connection.on("data", this.#onDataReceived.bind(this));
+    connection.on("close", () => {
+      if (this.#closeListener) this.#closeListener();
+    });
+    connection.on("error", (error) => {
+      if (this.#errorListener) this.#errorListener(error);
+    });
+  }
+
+  /**
+   * Sets the ABI cache to use for request (de)serialization.
+   * @param {ABICache} cache
+   */
+  setABICache(cache) {
+    this.#encodingOptions = { zlib, abiProvider: cache };
+  }
+
+  /**
+   * Registers a listener invoked when the wallet connection closes.
+   * @param {() => void} listener
+   */
+  onClose(listener) {
+    this.#closeListener = listener;
+  }
+
+  /**
+   * Registers a listener invoked when a connection error occurs.
+   * @param {(err: unknown) => void} listener
+   */
+  onError(listener) {
+    this.#errorListener = listener;
+  }
+
+  /**
+   * Indicates whether the wallet connection is still open.
+   * @return {boolean}
+   */
+  isOpen() {
+    return this.#connection.open;
+  }
+
+  /**
+   * Closes the connection to the wallet.
+   */
+  close() {
+    this.#connection.close();
+  }
+
+  /**
+   * The active permission level granted by the wallet.
+   * @return {PermissionLevel}
+   */
+  get permissionLevel() {
+    return this.#permissionLevel;
+  }
+
+  /**
+   * @param {PermissionLevel} value
+   */
+  set permissionLevel(value) {
+    this.#permissionLevel = value;
+  }
+
+  /**
+   * Convenience accessor for the actor name.
+   * @return {Name}
+   */
+  get actor() {
+    return this.#permissionLevel.actor;
+  }
+
+  /**
+   * Convenience accessor for the permission name.
+   * @return {Name}
+   */
+  get permission() {
+    return this.#permissionLevel.permission;
+  }
+
+  /**
+   * @typedef TransactArguments
+   * @property {Action} [action]     Single-action transaction
+   * @property {Action[]} [actions]  Multi-action transaction
+   * @property {Transaction} [transaction]  Fully-formed transaction
+   */
+
+  /**
+   * @typedef TransactOptions
+   * @property {boolean} [broadcast=true]  If true, broadcast on-chain; otherwise sign only.
+   */
+
+  /**
+   * Builds and sends a transaction request to the wallet.
+   * @param {TransactArguments} args
+   * @param {TransactOptions} [options]
+   * @return {Promise<SignedTransaction|import('@wharfkit/antelope').SendTransactionResponse>}
+   */
+  async transact(args, options) {
+    args.chainId = WalletSession.ChainID;
+    const willBroadcast =
+      options && typeof options.broadcast !== "undefined"
+        ? options.broadcast
+        : true;
+
+    const request = await SigningRequest.create(args, this.#encodingOptions);
+    request.setBroadcast(willBroadcast);
+
+    const vsr = request.encode(true, false, "vsr:");
+    return this.signingRequest(vsr);
+  }
+
+  /**
+   * Sends a VSR (Vexanium Signing Request) to the wallet.
+   * The wallet may broadcast the transaction immediately or return a signature only.
+   * @param {string} vsr
+   * @return {Promise<import('@wharfkit/antelope').SendTransactionResponse|SignedTransaction>}
+   */
+  signingRequest(vsr) {
+    const callback = window.crypto.randomUUID();
+    const data = {
+      method: "signingRequest",
+      id: callback,
+      params: { vsr }
+    };
+
+    return new Promise((resolve, reject) => {
+      const func = (reply) => {
+        if (reply.code === "SENT") {
+          resolve(reply.result);
+        } else if (reply.code === "SIGNED") {
+          resolve(SignedTransaction.from(reply.result));
+        } else {
+          // ERROR | REJECT
+          if (typeof reply.error === "string") {
+            reject(new Error(reply.error));
+          } else {
+            reject(reply.error);
+          }
+        }
+      };
+      this.#callbacks.set(callback, func);
+      this.#connection.send(data);
+    });
+  }
+
+  /**
+   * Requests a signature for an arbitrary message.
+   * @param {string} message  The message to be signed
+   * @return {Promise<Signature>}
+   */
+  signMessage(message) {
+    const callback = window.crypto.randomUUID();
+    const data = {
+      method: "signMessage",
+      id: callback,
+      params: { message }
+    };
+
+    return new Promise((resolve, reject) => {
+      const func = (reply) => {
+        if (reply.code === "SIGNED") {
+          resolve(Signature.from(reply.result.signature));
+        } else {
+          reject(new Error(reply.error.message));
+        }
+      };
+      this.#callbacks.set(callback, func);
+      this.#connection.send(data);
+    });
+  }
+
+  /**
+   * Derives a shared secret using ECDH with the wallet's key.
+   * @param {PublicKey} publicKey
+   * @return {Promise<Checksum512>}
+   */
+  sharedSecret(publicKey) {
+    const callback = window.crypto.randomUUID();
+    const data = {
+      method: "sharedSecret",
+      id: callback,
+      params: { key: publicKey.toString() }
+    };
+
+    return new Promise((resolve, reject) => {
+      const func = (reply) => {
+        if (reply.code === "CREATED") {
+          resolve(Checksum512.from(reply.result.secret));
+        } else if (reply.code === "ERROR") {
+          reject(new Error(reply.error));
+        }
+      };
+      this.#callbacks.set(callback, func);
+      this.#connection.send(data);
+    });
+  }
+
+  /**
+   * Handles incoming data from the wallet and resolves the pending callback.
+   * @param {{ id: string }} data
+   * @private
+   */
+  #onDataReceived(data) {
+    const callback = this.#callbacks.get(data.id);
+    if (callback) {
+      callback(data);
+      this.#callbacks.delete(data.id);
+    }
+  }
+}

package/src/WindConnector.js

@@ -0,0 +1,199 @@
+import { Base64u, IdentityProof, SigningRequest } from "@wharfkit/signing-request";
+import { Int64, PermissionLevel, Serializer } from "@wharfkit/antelope";
+import { Peer } from "peerjs";
+import zlib from "pako";
+import { WalletSession } from "./WalletSession.js";
+
+/**
+ * Handles communication with the signaling server
+ * and manages secure DApp ↔ Wallet sessions.
+ */
+export class WindConnector {
+    #peer;
+    #peerOptions = {};
+    #peerId;
+    #listeners = new Map();
+    #session = new Map();
+    #identityArgs = {};
+
+    constructor() {
+        this.#peerOptions.config = {
+            iceServers: [
+                { urls: "stun:stun.l.google.com:19302" },
+                { urls: "stun:stun1.l.google.com:3478" },
+                { urls: "stun:stun.relay.metered.ca:80" },
+                {
+                    urls: "turn:asia.relay.metered.ca:80",
+                    username: "b66cd40a117bddb5cde924ab",
+                    credential: "4jRmuTehVCZ2a/S+"
+                }
+            ],
+            sdpSemantics: "unified-plan"
+        };
+        this.#identityArgs.scope = "vexanium";
+        this.#identityArgs.chainId = WalletSession.ChainID;
+        this.#loadSession();
+    }
+
+    /**
+     * Adds an additional STUN or TURN server to the peer connection.
+     * @param {RTCIceServer} server
+     */
+    addIceServer(server) {
+        this.#peerOptions.config.iceServers.push(server);
+    }
+
+    /**
+     * Sets the signaling server address and port.
+     * @param {string} host
+     * @param {number} [port]
+     */
+    setServer(host, port) {
+        this.#peerOptions.host = host;
+        if (port) this.#peerOptions.port = port;
+    }
+
+    /**
+     * Registers a listener for specific peer events.
+     * Supported events: `open`, `close`, `disconnected`, `error`, `session`
+     * @param {string} event
+     * @param {Function} func
+     */
+    on(event, func) {
+        this.#listeners.set(event, func);
+    }
+
+    /**
+     * Connects to the signaling server.
+     * The wallet's response can be captured using the `session` event listener.
+     *
+     * @see on
+     * @see createLoginRequest
+     */
+    async connect() {
+        if (!this.#peerId) throw new Error("Peer ID is not set");
+        this.#peer = new Peer(this.#peerId, this.#peerOptions);
+        this.#peer.on("connection", this.#onConnection.bind(this));
+        this.#listeners.forEach((func, key) => {
+            this.#peer.on(key, func);
+        });
+    }
+
+    disconnect() {
+        this.#peer.disconnect();
+    }
+
+    destroy() {
+        this.#peer.destroy();
+    }
+
+    reconnect() {
+        this.#peer.reconnect();
+    }
+
+    isDisconnected() {
+        return this.#peer.disconnected;
+    }
+
+    isDestroyed() {
+        return this.#peer.destroyed;
+    }
+
+    /**
+     * Creates a VSR (Vexanium Signing Request) for login.
+     * @param {string} name - Application name
+     * @param {string} icon - Application icon URL
+     * @returns {string} Encoded VSR string for use in QR codes or query URLs
+     */
+    createLoginRequest(name, icon) {
+        const session = this.#getLastSession();
+        if (session) {
+            const [actor, perm] = session.permission.split("@");
+            this.#identityArgs.account = actor;
+            this.#identityArgs.permission = perm;
+            this.#peerId = session.peerId;
+        } else {
+            // Generate a new peer ID
+            this.#peerId = `VEX-${window.crypto.randomUUID()}`;
+        }
+        let req = SigningRequest.identity(this.#identityArgs, { zlib });
+        req.setInfoKey("pi", this.#peerId);
+        req.setInfoKey("na", name);
+        req.setInfoKey("ic", icon);
+        req.setInfoKey("do", window.location.origin);
+        if (session) {
+            req.setInfoKey("exp", Int64.from(session.exp));
+            req.setInfoKey("sig", session.signature);
+        }
+        return req.encode(true, false, "vsr:");
+    }
+
+    #getLastSession() {
+        const domain = window.location.origin;
+        let current = this.#session.get(domain);
+        if (current && current.exp < Date.now()) { // Expired
+            this.#session.delete(domain);
+            current = null;
+        }
+        return current;
+    }
+
+    #addSession(permission, exp, signature) {
+        const domain = window.location.origin;
+        let current = this.#session.get(domain);
+        if (current) {
+            current.permission = permission;
+            current.exp = exp;
+            current.signature = signature;
+        } else {
+            current = {
+                permission, exp, signature, domain, peerId: this.#peerId
+            };
+        }
+        this.#session.set(domain, current);
+    }
+
+    #saveSession() {
+        const data = Array.from(this.#session.values());
+        sessionStorage.setItem("session", JSON.stringify(data));
+    }
+
+    #loadSession() {
+        const raw = sessionStorage.getItem("session");
+        if (raw) {
+            let data = JSON.parse(raw);
+            data.forEach(it => {
+                this.#session.set(it.domain, it);
+            });
+        }
+    }
+
+    /**
+     * Handles incoming peer connections from the wallet.
+     * @param {DataConnection} conn
+     * @private
+     */
+    #onConnection(conn) {
+        conn.once("data", payload => {
+            if (payload.code === 'LOGIN_OK') {
+                const auth = Base64u.decode(payload.result.auth);
+                const proof = Serializer.decode({ data: auth, type: IdentityProof });
+                const session = new WalletSession(conn);
+                session.permissionLevel = proof.signer;
+
+                // Store session
+                this.#addSession(proof.signer.toString(), payload.result.exp, payload.result.signature);
+                this.#saveSession();
+
+                const func = this.#listeners.get("session");
+                if (func) func(session, proof);
+            } else if (payload.code === 'RE_LOGIN_OK') {
+                const session = new WalletSession(conn);
+                session.permissionLevel = PermissionLevel.from(payload.result.permission);
+
+                const func = this.#listeners.get("session");
+                if (func) func(session); // Only one parameter for re-login
+            }
+        });
+    }
+}