@luffalab/luffa-endless-sdk/README.md

luffa endless ts sdk

# Luffa Wallet Endless SDK Usage Guide
This document is intended for integrating Luffa Wallet into web-based DApps or embedded WebView pages within mini-programs using `@luffalab/luffa-endless-sdk` and `@endlesslab/endless-ts-sdk`.

---


## Installation

```bash
npm install @luffalab/luffa-endless-sdk
npm install @endlesslab/endless-ts-sdk
```
> ⚠️ For mini-programs: after installing `@luffalab/luffa-endless-sdk`, use the mini-program developer tool to compile the npm package.

---


## Import Modules

```ts
import {
  Network,
  EntryFunctionABI,
  TypeTagAddress,
  TypeTagU128,
  AccountAddress,
  EndlessConfig,
  Endless,
  AccountAuthenticator,
  Hex,
  Deserializer,
} from '@endlesslab/endless-ts-sdk';

import {
  EndlessLuffaSdk,
  UserResponseStatus,
  EndlessSignAndSubmitTransactionInput,
  EndlessWalletTransactionType,
  EndLessSDKEvent,
} from '@luffalab/luffa-endless-sdk';
```

---


## SDK Initialization

```ts
const jssdk = new EndlessLuffaSdk({
  network: 'testnet', // or 'mainnet'
});
```

---


## Wallet Connection

### Connect Wallet

```ts
const res = await jssdk.connect();
if (res.status === UserResponseStatus.APPROVED) {
  console.log('Account:', res.args.account);
}
```

### Disconnect Wallet

```ts
jssdk.disconnect();
console.log('Disconnect success');
```

### Get Current Account

```ts
const res = await jssdk.getAccount();
if (res.status === UserResponseStatus.APPROVED) {
  console.log('Current account:', res.args.account);
}
```

---


## Signing Features

### Sign Message

```ts
const res = await jssdk.signMessage({
  address: false,
  application: false,
  chainId: false,
  message: 'Welcome to dapp!',
  nonce: '1',
});
if (res.status === UserResponseStatus.APPROVED) {
  console.log(res.args);
}
```

Message format:

```
Endless::Message
message: Welcome to dapp!
nonce: 1
```

Return structure:

```ts
interface EndlessSignMessageOutput {
  address: string;
  application: string;
  chainId: number;
  fullMessage: string;
  message: string;
  nonce: string;
  prefix: string;
  signature: string;
}
```

---


## Transaction Features

### Sign and Submit Transaction

```ts
const abi: EntryFunctionABI = {
  typeParameters: [],
  parameters: [new TypeTagAddress(), new TypeTagU128()],
};

const txData: EndlessSignAndSubmitTransactionInput = {
  payload: {
    function: '0x1::endless_account::transfer',
    functionArguments: [
      AccountAddress.fromBs58String(toAccountAddress),
      BigInt(Number(transferAmount) * 1e8),
    ],
    abi,
  },
};

const res = await jssdk.signAndSubmitTransaction(txData);
if (res.status === UserResponseStatus.APPROVED) {
  console.log('Transaction submitted:', res);
}
```

### Generic Transaction with typeArguments

```ts
const txData: EndlessSignAndSubmitTransactionInput = {
  payload: {
    function: '0x1::endless_account::transfer_coins',
    functionArguments: [
      AccountAddress.fromBs58String(toAccountAddress),
      BigInt(Number(transferAmount) * 1e8),
      coinAddress,
    ],
    typeArguments: ['0x1::fungible_asset::Metadata'],
  },
};
```
### Mini-program Usage Notes

When using Luffa SDK inside a mini-program:

* Do not use `@endlesslab/endless-ts-sdk` to construct transactions.
* Do not use `BigInt` types — use `string` instead.
* You must provide `typeArguments` explicitly.

Example:

```ts
const txData: EndlessSignAndSubmitTransactionInput = {
  payload: {
    function: '0x1::endless_account::transfer',
    functionArguments: [
      toAccountAddress, // string
      String(transferAmount * 1e8) // also string
    ],
    typeArguments: ['address', 'u128'],
  },
};
```
### Sign Only (without Submit)

```ts
const config = new EndlessConfig({ network: Network.TESTNET });
const endless = new Endless(config);

const txn = await endless.transaction.build.simple({
  sender: accountAddress,
  data: txData.payload,
});
const hexTxn = txn.bcsToHex().toString();

const res = await jssdk.signTransaction(hexTxn, EndlessWalletTransactionType.SIMPLE);
if (res.status === UserResponseStatus.APPROVED) {
  const data = Hex.fromHexString(res.args.data).toUint8Array();
  const deserializer = new Deserializer(data);
  const auth = AccountAuthenticator.deserialize(deserializer);
  console.log('AccountAuthenticator:', auth);
}
```

---


## Change Network

```ts
jssdk.changeNetwork({
  network: Network.MAINNET,
});
```

---


## Event Listeners

```ts
jssdk.on(EndLessSDKEvent.CONNECT, (res) => {
  console.log('Wallet connected:', res);
});

jssdk.on(EndLessSDKEvent.DISCONNECT, () => {
  console.log('Wallet disconnected');
});

jssdk.on(EndLessSDKEvent.ACCOUNT_CHANGE, (res) => {
  console.log('Account changed:', res);
});

jssdk.on(EndLessSDKEvent.NETWORK_CHANGE, (networkInfo) => {
  console.log('Network changed:', networkInfo);
});
```

---


## Notes

* All amounts are in the smallest unit (e.g., 1 EDS = 1e8).
* For generic ABI functions, make sure to manually provide `typeArguments`.
* It is recommended to always use SDK methods for transactions instead of crafting them manually.

---


For additional features or technical support, please contact the Luffa team.