npm package: @fastxyz/fast-connector
Description: Dapp-facing connector for injected Fast wallets
Author: Fast.xyz
Latest version: 0.1.2

# `@fastxyz/fast-connector`

Dapp-facing connector for injected Fast wallets.

## Positioning

- `@fastxyz/sdk` is the low-level Fast client layer, parallel to `viem` or `ethers`
- `window.fastset` is the injected wallet surface, parallel to `window.ethereum`
- `@fastxyz/fast-connector` is the app-facing wallet adapter layer, parallel to a wagmi injected connector or an app wrapper around `ethers.BrowserProvider(window.ethereum)`

This package is for browser apps such as InfoFi. It is not for extension-internal wallet logic.

The extension still owns:

- key management
- permissions and approval UI
- signing
- transaction submission

This package owns:

- injected wallet detection
- adapter typing
- dapp-facing connection state
- a reusable app connector over `window.fastset`
- optional provider-backed reads through `@fastxyz/sdk`
- high-level transaction helpers over injected wallet methods

## Status

This repo includes:

- injected wallet detection and waiting for `fastset#initialized`
- connection/account state
- message signing
- provider-backed read helpers for balances, tokens, certificates, and explorer URLs
- high-level `transfer()` and `submitClaim()` wrappers
- a `@fastxyz/fast-connector/testing` entrypoint for reusable wallet mocks

It intentionally does not own onramp/vendor logic. Swapper, AllSet, and fiat adapters should live in `fast-onramp`.

## Planned Usage

```ts
import { FastConnector } from '@fastxyz/fast-connector';

const connector = FastConnector.fromInjected(window.fastset);
await connector.connect();

const account = await connector.exportKeys();
const signed = await connector.sign({ message: 'hello fast' });
const balance = await connector.getBalance('FAST');
const payment = await connector.transfer({
  recipient: 'fast1...',
  amount: '0x32',
});
const explorerUrl = await connector.getExplorerUrl(payment.txHash);
const claim = await connector.submitClaim({
  claimData: [1, 2, 3],
});
```

`submitClaim()` maps to Fast `ExternalClaim` submission and accepts only claim payload fields such as `claimData`, `verifierCommittee`, `verifierQuorum`, and `signatures`.

You can also inject a custom read provider, or let the connector build one from the installed SDK:

```ts
import { FastConnector } from '@fastxyz/fast-connector';

const connector = FastConnector.fromInjected(window.fastset, {
  providerOptions: {
    network: 'mainnet',
  },
});

await connector.connect();
const tokens = await connector.getTokens();
const network = await connector.getNetwork();
```

## Testing

`@fastxyz/fast-connector/testing` provides reusable mocks for app and integration tests:

```ts
import { FastConnector } from '@fastxyz/fast-connector';
import {
  createMockAccount,
  createMockInjectedFastConnector,
  dispatchFastsetInitialized,
} from '@fastxyz/fast-connector/testing';

const wallet = createMockInjectedFastConnector();
window.fastset = wallet;
dispatchFastsetInitialized(window);

const connector = FastConnector.fromInjected(wallet);
await connector.connect();

wallet.mock.emitAccountChanged(createMockAccount({
  publicKey: 'bb'.repeat(32),
  injected: true,
}));
```

The testing entrypoint includes:

- mock injected wallet factory
- canonical and injected mock accounts
- mock transfer and claim certificates
- helpers for `fastset#initialized`
- helpers for account-change events

## Development

```bash
npm install
npm run build
npm test
```

## SDK Compatibility

`@fastxyz/fast-connector` now targets `@fastxyz/sdk@^1.0.1`.

- The connector no longer imports `@fastxyz/sdk/browser`
- Built-in provider reads are created from `new FastProvider({ rpcUrl })`
- Network and token metadata used by the connector are owned here, with optional overrides through `providerOptions`