@azguardwallet/types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Azguard Wallet
+
+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,61 @@
+# @azguardwallet/types
+
+This library contains type declarations with annotations for Azguard Wallet inpage RPC client, that can be helpful for browser based apps written in TypeScript.
+
+### How to use
+
+Install the package:
+
+```shell
+npm install @azguardwallet/types --save-dev
+```
+
+And import it somewhere in your codebase:
+
+```ts
+import "@azguardwallet/types";
+```
+
+After that TS will be aware of `window.azguard` object and all related types.
+
+### Example
+
+```ts
+import type {
+    CaipAccount,
+    CallAction,
+    FailedResult,
+    OkResult,
+} from "@azguardwallet/types";
+
+const azguard = window.azguard.createClient();
+
+const account: CaipAccount = "aztec:31337:0xffff...";
+
+const transferCall: CallAction = {
+    kind: "call",
+    contract: "0xffff...",
+    method: "transfer",
+    args: ["0xffff...", 100],
+};
+
+const [result] = await azguard.request("execute", {
+    sessionId: "1234",
+    operations: [
+        {
+            kind: "send_transaction",
+            account: account,
+            actions: [transferCall],
+        },
+    ],
+});
+
+if (result.kind === "ok") {
+    const txHash = (result as OkResult<string>).result;
+    // ...
+}
+else if (result.kind === "failed") {
+    const error = (result as FailedResult).error;
+    // ...
+}
+```

package/dist/action.d.ts

@@ -0,0 +1,56 @@
+import { AuthwitContent } from "./authwit-content";
+/** Action kind */
+export type ActionKind = "add_capsule" | "add_private_authwit" | "add_public_authwit" | "call" | "call_ext";
+/** A request to perform some action */
+export type Action = AddCapsuleAction | AddPrivateAuthwitAction | AddPublicAuthwitAction | CallAction | CallExtAction;
+/** A request to add a capsule to PXE */
+export type AddCapsuleAction = {
+    /** Action kind */
+    kind: "add_capsule";
+    /** Capsule to be added (Fr[]) */
+    capsule: string[];
+};
+/** A request to add an authwit for the message hash computed from the given content to PXE */
+export type AddPrivateAuthwitAction = {
+    /** Action kind */
+    kind: "add_private_authwit";
+    /** Original content from which a message hash will be comupted */
+    content: AuthwitContent;
+};
+/** A request to call the AuthRegistry contract to authorize message hash computed from the given content */
+export type AddPublicAuthwitAction = {
+    /** Action kind */
+    kind: "add_public_authwit";
+    /** Original content from which a message hash will be comupted */
+    content: AuthwitContent;
+};
+/** A request to call a contract with plain args */
+export type CallAction = {
+    /** Action kind */
+    kind: "call";
+    /** Address of the contract (AztecAddress) */
+    contract: string;
+    /** Name of the function */
+    method: string;
+    /** Arguments (unencoded) */
+    args: any[];
+};
+/** A request to call a contract with encoded args (matches FunctionCall from aztec.js) */
+export type CallExtAction = {
+    /** Action kind */
+    kind: "call_ext";
+    /** Name of the function */
+    name: string;
+    /** Address of the contract (AztecAddress) */
+    to: string;
+    /** Selector of the function (FunctionSelector) */
+    selector: string;
+    /** Type of the function (FunctionType) */
+    type: string;
+    /** Whether this call can makes modifications to state or not */
+    isStatic: boolean;
+    /** Encoded arguments (Fr[]) */
+    args: string[];
+    /** Return types for decoding (AbiType[]) */
+    returnTypes: unknown[];
+};

package/dist/authwit-content.d.ts

@@ -0,0 +1,31 @@
+/** Content to add authwitness for. */
+export type AuthwitContent = CallAuthwitContent | IntentAuthwitContent | MessageHashAuthwitContent;
+/** Contract call to be authorized */
+export type CallAuthwitContent = {
+    /** Authwit content kind */
+    kind: "call";
+    /** Address of the caller (AztecAddress) */
+    caller: string;
+    /** Address of the contract (AztecAddress) */
+    contract: string;
+    /** Name of the function */
+    method: string;
+    /** Arguments (unencoded) */
+    args: any[];
+};
+/** Arbitrary intent to be authorized */
+export type IntentAuthwitContent = {
+    /** Authwit content kind */
+    kind: "intent";
+    /** Address of the authwitness consumer (AztecAddress) */
+    consumer: string;
+    /** Intent (Fr[]) */
+    intent: string[];
+};
+/** Message hash to be authorized */
+export type MessageHashAuthwitContent = {
+    /** Authwit content kind */
+    kind: "message_hash";
+    /** Message hash (Fr) */
+    messageHash: string;
+};

package/dist/client.d.ts

@@ -0,0 +1,92 @@
+import { DappMetadata, DappPermissions, DappSession } from "./dapp-session";
+import { Operation, OperationResult } from "./operation";
+/** Azguard RPC client for sending requests to and receiving events from the wallet */
+export type AzguardRpcClient = {
+    /**
+     * Adds event handler for the `session_updated` event
+     * @param event event name
+     * @param handler event handler
+     */
+    on(event: "session_updated", handler: (session: DappSession) => void): void;
+    /**
+     * Adds event handler for the `session_closed` event
+     * @param event event name
+     * @param handler event handler
+     */
+    on(event: "session_closed", handler: (session: DappSession) => void): void;
+    /**
+     * Removes event handler for the `session_updated` event
+     * @param event event name
+     * @param handler event handler
+     */
+    off(event: "session_updated", handler: (session: DappSession) => void): void;
+    /**
+     * Removes event handler for the `session_closed` event
+     * @param event event name
+     * @param handler event handler
+     */
+    off(event: "session_closed", handler: (session: DappSession) => void): void;
+    /**
+     * Requests wallet info
+     * @param method RPC method name
+     * @returns Wallet info
+     */
+    request(method: "get_wallet_info"): Promise<WalletInfo>;
+    /**
+     * Requests session info
+     * @param method RPC method name
+     * @param sessionId Session id
+     * @returns Dapp session or `null` if not found
+     */
+    request(method: "get_session", sessionId: string): Promise<DappSession | null>;
+    /**
+     * Requests session termination
+     * @param method RPC method name
+     * @param sessionId Session id
+     * @returns Closed dapp session or `null` if not found
+     */
+    request(method: "close_session", sessionId: string): Promise<DappSession | null>;
+    /**
+     * Requests connection to the wallet
+     * @param method RPC method name
+     * @param params Connection parameters
+     * @returns Created dapp session
+     * @throws "User rejected" if user rejects
+     */
+    request(method: "connect", params: {
+        /** Information about the connected DApp */
+        dappMetadata: DappMetadata;
+        /** Required permissions requested by the DApp */
+        requiredPermissions: DappPermissions[];
+        /** Optional permissions requested by the DApp */
+        optionalPermissions?: DappPermissions[];
+    }): Promise<DappSession>;
+    /**
+     * Requests execution of a batch of operations
+     * @param method RPC method name
+     * @param params Execution parameters
+     * @returns List of operation results, fully matching the list of requested operations
+     * @throws "User rejected" if user rejects
+     */
+    request(method: "execute", params: {
+        /** Id of the session */
+        sessionId: string;
+        /** List of operations to execute */
+        operations: Operation[];
+    }): Promise<OperationResult[]>;
+};
+/** Wallet metadata */
+export type WalletInfo = {
+    /** Name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Logo URI */
+    logo: string;
+    /** Wallet URI */
+    url: string;
+    /** Version */
+    version: string;
+    /** Capabilities */
+    capabilities: string[];
+};

package/dist/dapp-session.d.ts

@@ -0,0 +1,35 @@
+import { ActionKind } from "./action";
+import { OperationKind } from "./operation";
+/** Chain id (CAIP-2) */
+export type CaipChain = `aztec:${number}`;
+/** Accound address (CAIP-10) */
+export type CaipAccount = `${CaipChain}:${string}`;
+/** DApp metadata */
+export type DappMetadata = {
+    /** Name */
+    name: string;
+    /** Short description */
+    description?: string;
+    /** Logo URI */
+    logo?: string;
+    /** DApp URI */
+    url?: string;
+};
+/** Permissions set */
+export type DappPermissions = {
+    /** List of chains */
+    chains?: CaipChain[];
+    /** List of methods */
+    methods?: (OperationKind | ActionKind)[];
+    /** List of events */
+    events?: CaipAccount[];
+};
+/** Dapp session */
+export type DappSession = {
+    /** Id of the session */
+    id: string;
+    /** Approved permissions */
+    permissions: DappPermissions[];
+    /** Approved accounts */
+    accounts: CaipAccount[];
+};

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { AzguardRpcClient } from "./client";
+declare global {
+    interface Window {
+        /**
+         * Azguard Wallet accessor
+         */
+        azguard: {
+            /**
+             * Version
+             */
+            version: string;
+            /**
+             * Creates an RPC client for interaction with the Azguard Wallet
+             * @returns a new instance of AzguardRpcClient
+             */
+            createClient: () => AzguardRpcClient;
+        };
+    }
+}
+export * from "./action";
+export * from "./authwit-content";
+export * from "./client";
+export * from "./dapp-session";
+export * from "./operation";
+export * from "./result";

package/dist/operation.d.ts

@@ -0,0 +1,116 @@
+import { Action } from "./action";
+import { Result } from "./result";
+import { CaipAccount, CaipChain } from "./dapp-session";
+/** Operation kind */
+export type OperationKind = "add_note" | "register_contract" | "register_sender" | "send_transaction" | "simulate_transaction" | "simulate_unconstrained";
+/** A request to perform some operation */
+export type Operation = AddNoteOperation | RegisterContractOperation | RegisterSenderOperation | SendTransactionOperation | SimulateTransactionOperation | SimulateUnconstrainedOperation;
+/** Operation result */
+export type OperationResult = AddNoteResult | RegisterContractResult | RegisterSenderResult | SendTransactionResult | SimulateTransactionResult | SimulateUnconstrainedResult;
+/** A request to add a note to PXE */
+export type AddNoteOperation = {
+    /** Operation kind */
+    kind: "add_note";
+    /** Account to add the note for */
+    account: CaipAccount;
+    /** Extended note, converted to string */
+    note: string;
+};
+/** A result of the "add_note" operation */
+export type AddNoteResult = Result<void>;
+/** A request to register contract in PXE */
+export type RegisterContractOperation = {
+    /** Operation kind */
+    kind: "register_contract";
+    /** Chain to register the contract for */
+    chain: CaipChain;
+    /** Address of the contract (AztecAddress) */
+    address: string;
+    /**
+     * Contract instance (ContractInstanceWithAddress).
+     * If not specified, the wallet will try to fetch it from PXE/node.
+     */
+    instance?: unknown;
+    /**
+     * Contract artifact (ContractArtifact).
+     * If not specified, the wallet will try to fetch it from PXE/node.
+     */
+    artifact?: unknown;
+};
+/** A result of the "register_contract" operation */
+export type RegisterContractResult = Result<void>;
+/** A request to register sender in PXE */
+export type RegisterSenderOperation = {
+    /** Operation kind */
+    kind: "register_sender";
+    /** Chain to register the sender for */
+    chain: CaipChain;
+    /** Address of the sender (AztecAddress) */
+    address: string;
+};
+/** A result of the "register_sender" operation */
+export type RegisterSenderResult = Result<void>;
+/** A request to send the transaction */
+export type SendTransactionOperation = {
+    /** Operation kind */
+    kind: "send_transaction";
+    /** Address of the account to send transaction from */
+    account: CaipAccount;
+    /**
+     * Batch of calls to be passed to the account contract for the "execution" phase
+     * and additional actions, that may be needed for its execution
+     * */
+    actions: Action[];
+    /**
+     * Batch of calls to be passed to the account contract for the "setup" phase
+     * and additional actions, that may be needed for its execution
+     * */
+    setup?: Action[];
+};
+/** A result of the "send_transaction" operation (TxHash) */
+export type SendTransactionResult = Result<string>;
+/** A request to simulate the transaction */
+export type SimulateTransactionOperation = {
+    /** Operation kind */
+    kind: "simulate_transaction";
+    /** Address of the account to send transaction from */
+    account: CaipAccount;
+    /**
+     * Batch of calls to be passed to the account contract for the "execution" phase
+     * and additional actions, that may be needed for its execution
+     * */
+    actions: Action[];
+    /**
+     * Batch of calls to be passed to the account contract for the "setup" phase
+     * and additional actions, that may be needed for its execution
+     * */
+    setup?: Action[];
+    /** Whether to also simulate enqueued public calls or not */
+    simulatePublic?: boolean;
+};
+/** Wrapped simulation results */
+export type SimulationReturn = {
+    /** Gas usage info (GasUsed) */
+    gasUsed: unknown;
+    /** Private return values (NestedProcessReturnValues) */
+    privateReturn: unknown;
+    /** Public return values (NestedProcessReturnValues[]) */
+    publicReturn: unknown[];
+};
+/** A result of the "simulate_transaction" operation */
+export type SimulateTransactionResult = Result<SimulationReturn>;
+/** A request to simulate the unconstrained function */
+export type SimulateUnconstrainedOperation = {
+    /** Operation kind */
+    kind: "simulate_unconstrained";
+    /** Address of the account to simulate for */
+    account: CaipAccount;
+    /** Address of the contract (AztecAddress) */
+    contract: string;
+    /** Name of the function */
+    method: string;
+    /** Arguments (unencoded) */
+    args: any[];
+};
+/** A result of the "simulate_unconstrained" operation (AbiDecoded) */
+export type SimulateUnconstrainedResult = Result<unknown>;

package/dist/result.d.ts

@@ -0,0 +1,24 @@
+/** Result object */
+export type Result<T> = OkResult<T> | FailedResult | SkippedResult;
+/** Successful result, containing returned value */
+export type OkResult<T> = {
+    /** Result kind */
+    kind: "ok";
+    /** Returned value */
+    result: T;
+};
+/** Failed result, containing error message */
+export type FailedResult = {
+    /** Result kind */
+    kind: "failed";
+    /** Returned error */
+    error: string;
+};
+/**
+ * Skipped result, meaning that the operation was skipped
+ * due to one of the previous operations in the same batch failed
+ * */
+export type SkippedResult = {
+    /** Result kind */
+    kind: "skipped";
+};

package/package.json

@@ -0,0 +1,19 @@
+{
+    "name": "@azguardwallet/types",
+    "version": "0.1.0",
+    "description": "Typings for Azguard Wallet inpage RPC client",
+    "author": "Azguard Wallet",
+    "homepage": "https://github.com/AzguardWallet/azguard-wallet-types",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/AzguardWallet/azguard-wallet-types.git"
+    },
+    "license": "MIT",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "rm -rf dist && tsc"
+    }
+}