KIP-0037 to KIP-0041: Standardized JSON-RPC Methods for Wallet-DApp Communication

kip-0037.md

@@ -0,0 +1,147 @@
+---
+KIP: '0037'
+Title: kadena_getAccount_v1 API
+Author: Danillo Felixdaal, Bart Huijgen and Albert Groothedde
+Status: Draft
+Type: Standard
+Category: Interface
+Created: 2025-02-17
+---
+
+# kadena_getAccount_v1 API
+
+## Abstract
+
+This KIP standardizes the `kadena_getAccount_v1` method to provide the active
+account known by the wallet. This allows dApps to present the user with the
+currently selected account and use it for creating and signing transactions.
+
+## Motivation
+
+The `kadena_getAccount_v1` method provides a standardized way to retrieve a
+single, active account from a Kadena wallet. This method is used when the dApp
+does not need to specify which account to retrieve and relies on the wallet's
+current active selection.
+
+## Specification
+
+### Method Definition
+
+**Method Name:** `kadena_getAccount_v1`
+
+#### Parameters
+
+No parameters required. The wallet can return any account that is currently
+active.
+
+### Response
+
+```typescript
+interface AccountInfo {
+  accountName: string; // The unique identifier for the account.
+  networkId: string; // The unique identifier for the network for this account.
+  contract: string; // Identifier for the fungible token contract.
+  guard: {
+    keys: string[]; // Array of public keys (secret keys are omitted for security).
+    pred: string; // Predicate defining key validation (e.g., "keys-all", "keys-any").
+  };
+  chainAccounts: string[]; // Array of chain IDs where this account exists
+}
+```
+
+> **Note:** The `chainAccounts` can be empty when there are no minted accounts
+> on-chain.
+
+### Error Responses
+
+In case of failure, the wallet **MUST** return an error according to the
+[JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification#error_object):
+
+```typescript
+interface ErrorResponse {
+  id: number;
+  jsonrpc: '2.0';
+  error: {
+    code: number;
+    message: string;
+    data?: object;
+  };
+}
+```
+
+#### Error Types
+
+| Code   | Message               |
+| ------ | --------------------- |
+| -32603 | Internal server error |
+
+### Behavior Requirements
+
+1. **Account Retrieval:**
+   - **MUST** return accurate and up-to-date information about the active
+     account.
+2. **Error Handling:**
+   - **MUST** return a clear error if account information cannot be retrieved
+     due to configuration issues.
+
+## Examples
+
+### Retrieve Active Account from Wallet
+
+#### Example Request
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "method": "kadena_getAccount_v1"
+}
+```
+
+#### Example Response
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "result": {
+    "accountName": "k:35d381861d9a6cfb84bef47930b386d1a3b4f3742c8e87772a9e6b43c0e7b5f7",
+    "networkId": "mainnet01",
+    "contract": "coin",
+    "guard": {
+      "keys": [
+        "35d381861d9a6cfb84bef47930b386d1a3b4f3742c8e87772a9e6b43c0e7b5f7"
+      ],
+      "pred": "keys-all"
+    },
+    "chainAccounts": ["0", "1"]
+  }
+}
+```
+
+### Error Response Example
+
+```json
+{
+  "id": 1,
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32603,
+    "message": "Internal server error"
+  }
+}
+```
+
+## Backwards Compatibility
+
+- **Legacy Methods:** Wallets **MAY** support older methods for retrieving
+  account information alongside `kadena_getAccount_v1`. Legacy methods **MUST**
+  be documented as deprecated and phased out over time.
+
+- **Configuration Consistency:** Implementations **MUST** ensure that the
+  returned account information matches the wallet's active configuration.
+
+## Security Considerations
+
+- **Data Accuracy:** Ensure that the returned account information is accurate
+  and verified.