# Wallet API

The API is designed for dApps to:

* Connect to the user’s wallet
* Read identity + balance
* Sign messages
* Construct/sign/push Trac Network (TNK) transfers
* Sign Trac **contract** transactions (for `trac-peer`)

This page is based on the reference implementation in `tap-wallet-extension` (main branch) in this workspace.

### Conventions

* All methods are async and return Promises.
* Hex strings are lowercase/uppercase tolerant unless stated otherwise.
* Addresses are bech32m strings with `trac1...` prefix.
* Amounts/balances are returned as strings (typically smallest-unit / integer strings).

### Methods

#### `tracnetwork.requestAccount()`

Connects the wallet and returns the connected address.

* Params: none
* Returns: `Promise<string>` (wallet address)

```js
const address = await window.tracnetwork.requestAccount();
```

Example response:

```txt
trac1wnky35sgxefesuja46yvyf3tmf7pneeqv3ns5pk5pjlzu082f23s4r7923
```

#### `tracnetwork.getAddress()`

Returns the currently connected address.

* Params: none
* Returns: `Promise<string>` (wallet address)

```js
const address = await window.tracnetwork.getAddress();
```

#### `tracnetwork.getBalance()`

Returns the TNK balance of the connected account.

* Params: none
* Returns: `Promise<string>` (balance)

```js
const balance = await window.tracnetwork.getBalance();
```

Example response:

```txt
938000000000000000
```

#### `tracnetwork.getNetwork()`

Returns the current wallet network.

* Params: none
* Returns: `Promise<string>` (typically `"livenet"` or `"testnet"`)

```js
const network = await window.tracnetwork.getNetwork();
```

#### `tracnetwork.switchNetwork(network)`

Switches wallet network.

* Params:
  * `network: string` (accepted values include `"livenet"`, `"mainnet"`, `"testnet"`)
* Returns: `Promise<string>` (network name, e.g. `"testnet"`)

```js
await window.tracnetwork.switchNetwork("testnet");
```

Example response:

```txt
testnet
```

#### `tracnetwork.getPublicKey()`

Returns the connected wallet public key (hex).

* Params: none
* Returns: `Promise<string>` (public key hex, 32 bytes / 64 hex chars)

```js
const pubKey = await window.tracnetwork.getPublicKey();
```

Example response:

```txt
74ec48d208365398725dae88c2262bda7c19e72064670a06d40cbe2e3cea4aa3
```

#### `tracnetwork.signMessage(message)`

Signs an arbitrary message.

* Params:
  * `message: string`
* Returns: `Promise<{ signature: string, publicKey: string, address: string }>`

```js
const sig = await window.tracnetwork.signMessage("hello");
```

Example response shape:

```json
{
  "signature": "<hex-signature>",
  "publicKey": "<hex-publicKey>",
  "address": "trac1..."
}
```

Notes:

* Signing semantics are wallet-implementation-defined (what bytes are signed).
* When using this for a protocol that verifies signatures, ensure the verifier uses the same message bytes the wallet signed.

#### `tracnetwork.sendTNK(from, to, amount)`

Transfers TNK (high-level helper).

* Params:
  * `from: string`
  * `to: string`
  * `amount: string | number`
* Returns: `Promise<{ txHash: string, success: boolean }>`

```js
const res = await window.tracnetwork.sendTNK(fromAddress, toAddress, "1");
```

Example response:

```json
{
  "txHash": "6f7d901d63405873f3e845858b213603762bc4a1846a3f197a5a85092f84dd73",
  "success": true
}
```

#### `tracnetwork.buildTracTx({ from?, to, amount })`

Builds **and signs** a Trac Network TNK transfer and returns a broadcastable payload (base64 string).

* Params:
  * `{ from?: string, to: string, amount: string | number }`
* Returns: `Promise<string>` (`txPayload`, base64)

```js
const txPayload = await window.tracnetwork.buildTracTx({ to: recipient, amount: "1" });
```

#### `tracnetwork.pushTracTx(txPayload)`

Pushes a signed Trac Network transfer transaction payload (from `buildTracTx`) to the network.

* Params:
  * `txPayload: string` (base64)
* Returns: `Promise<{ txHash: string, success: boolean }>`

```js
const result = await window.tracnetwork.pushTracTx(txPayload);
```

Example response:

```json
{
  "txHash": "c3ce135ccc8e5d27b1b9ed153b05fada9937c5bf07085c4dbde601cb763f33e4",
  "success": true
}
```

#### `tracnetwork.signTracTx(contractTx)`

Signs a **contract transaction** (used with `trac-peer` contract RPC flows).

* Params:
  * `contractTx: { prepared_command: object, nonce: string, context: object }`
* Returns: `Promise<{ tx: string, signature: string }>`

Minimal example (shape):

```json
{
  "prepared_command": { "type": "catch", "value": {} },
  "nonce": "<hex32>",
  "context": {
    "networkId": 918,
    "txv": "<hex32>",
    "iw": "<hex32>",
    "bs": "<hex32 | optional>",
    "mbs": "<hex32>"
  }
}
```

Return value:

```json
{
  "tx": "<hex32>",
  "signature": "<hex64>"
}
```