@secux/app-sui

SecuX Hardware Wallet SUI API

Usage

import { SecuxSUI } from "@secux/app-sui";
import { SuiCurve } from "@secux/app-sui/interface";

First, create instance of ITransport

• Web Usb
• Web Bluetooth
• React Native Bluetooth

Examples

1. Get address of bip44 path

const path = "m/44'/784'/0'/0'/0'";
const address = await device.getAddress(path);

/*

// transfer data to hardware wallet by custom transport layer.
const data = SecuxSUI.prepareAddress(path);
const response = await device.Exchange(data);
const address = SecuxSUI.resolveAddress(response);

*/

2. Sign with explicit Coin/Object inputs

Use prepareSignObject when the transaction consumes owned Coin objects or transfers NFT objects. Transaction building is fully offline; all object refs and gas data must already be resolved by the backend.

const path = "m/44'/784'/0'/0'/0'";
const publickey = await device.getPublickey(path);
const content = {
  publickey,
  to: "0x89ad0df73ca35d48721c0ad146e2e50ed685324578b8a531f8f35f1c44ba278d",
  amount: "1000000000", // 1 SUI in MIST
  type: "0x2::sui::SUI",
  gasPrice: "1000",
  gasBudget: "5000000",
  gasPayment: [{ objectId: "0x...", version: "123", digest: "..." }],
  expiration: { None: true },
};

const { commandData, rawTx } = await SecuxSUI.prepareSignObject(path, content);
const response = await device.Exchange(commandData);
const { bytes, signature } = SecuxSUI.resolveTransaction(response, {
  rawTx,
  publickey,
  curve: SuiCurve.ED25519,
});

For a custom token object transfer, add tokens containing the token Coin object refs. For an NFT transfer, use nfts instead of amount/tokens.

3. Sign from Address Balance

Use prepareSignAddress only when both the transferred asset and, when gasPayment is empty, gas are paid from Address Balance. It constructs the official Sui framework calls 0x2::balance::redeem_funds and 0x2::balance::send_funds locally and does not require a Sui client.

const content = {
  publickey,
  to: "0x89ad0df73ca35d48721c0ad146e2e50ed685324578b8a531f8f35f1c44ba278d",
  amount: "1011778",
  type: "0x...::usdc::USDC",
  gasPrice: "1000",
  gasBudget: "5000000",
  gasPayment: [],
  expiration: {
    ValidDuring: {
      minEpoch: "555",
      maxEpoch: "556",
      minTimestamp: null,
      maxTimestamp: null,
      chain: "<base58 encoded 32-byte chain identifier>",
      nonce: 123456789,
    },
  },
};

const { commandData, rawTx } = await SecuxSUI.prepareSignAddress(path, content);

An empty gasPayment explicitly selects Address Balance gas and requires an expiration. Supplying Coin object refs selects object gas.

4. Sign a backend-resolved TransactionKind

Use prepareSignBalance when an online backend has built an official TransactionKind, for example from Transaction#balance(). The frontend stays offline: the backend returns the BCS TransactionKind plus the complete GasData, and the SDK assembles and signs TransactionData locally.

const content = {
  publickey,
  to: "0x89ad0df73ca35d48721c0ad146e2e50ed685324578b8a531f8f35f1c44ba278d",
  amount: "1000000000",
  type: "0x2::sui::SUI",
  transactionKind: backendResult.transactionKind, // base64 BCS TransactionKind
  gasPrice: backendResult.gasPrice,
  gasBudget: backendResult.gasBudget,
  gasPayment: backendResult.gasPayment,
  gasOwner: backendResult.gasOwner,
  expiration: backendResult.expiration,
};

const { commandData, rawTx } = await SecuxSUI.prepareSignBalance(path, content);

prepareSignBalance does not sign arbitrary serialized transactions. Before signing it validates sender, recipient, exact amount, coin type and command shape. Only owned object/pure/address-withdrawal inputs, merge/split commands, and these Sui framework calls are accepted:

• 0x2::balance::redeem_funds
• 0x2::balance::send_funds
• 0x2::coin::redeem_funds
• 0x2::coin::into_balance
• 0x2::coin::send_funds

Custom Move packages and unrelated transaction commands are rejected.

prepareSign(path, content) remains available as a dispatcher:

• transactionKind present: prepareSignBalance
• tokens or nfts present: prepareSignObject
• otherwise: prepareSignAddress

Backend and offline signing boundary

The frontend signing APIs do not create an SuiClient and do not query the network. The backend must resolve current object refs, gas price, gas budget, GasData, expiration and any TransactionKind that depends on chain state. Dry-run the exact full transaction bytes assembled from those values before returning the signing content. The signed bytes submitted for broadcast must be identical to the dry-run bytes.

Firmware content v2

Deterministic firmware vectors cover SUI and custom tokens across:

• pure Coin/Object transfer
• pure Address Balance transfer
• backend-resolved TransactionKind using address, object or mixed funding
• object gas or Address Balance gas

Generate all 16 vectors with:

npm run vectors:firmware:v2 --workspace=@secux/app-sui

The generated fixtures are under __tests__/firmware-content-v2. They include the request, raw TransactionData, intent signing payload, APDU command, decoded transaction and expected policy fields.

The fixture mnemonic is only for deterministic testing. Sui signing is not restricted to 24-word mnemonics; valid 12-, 18- and 24-word BIP39 seeds can sign. However, fixture public keys, sender addresses and transaction bytes are tied to the fixture seed. A physical device must use that seed, or the vectors must be regenerated for the device's public key and sender, for signature verification and broadcast to succeed.

API Reference

SUI package for SecuX device

Kind: global class

• SecuxSUI
  • .addressConvert(publickey, curve) ⇒ string
  • .prepareAddress(path) ⇒ communicationData
  • .resolveAddress(response, curve) ⇒ string
  • .preparePublickey(path) ⇒ communicationData
  • .resolvePublickey(response) ⇒ string
  • .prepareSign(path, content) ⇒ prepared
  • .resolveSignature(response) ⇒ string
  • .resolveTransaction(response, params) ⇒ string

SecuxSUI.addressConvert(publickey, curve) ⇒ string

Convert bip32-publickey to SUI address.

Returns: string - address

| Param | Type | Description | | --- | --- | --- | | publickey | string | Buffer | ada bip32-publickey | | curve | EllipticCurve | |

SecuxSUI.prepareAddress(path) ⇒ communicationData

Prepare data for address generation.

Returns: communicationData - data for sending to device

| Param | Type | Description | | --- | --- | --- | | path | string | m/1852'/1815'/... |

SecuxSUI.resolveAddress(response, curve) ⇒ string

Resolve address from response data.

Returns: string - address

| Param | Type | Description | | --- | --- | --- | | response | communicationData | data from device | | curve | SuiCurve | |

SecuxSUI.preparePublickey(path) ⇒ communicationData

Prepare data for ed25519 publickey.

Returns: communicationData - data for sending to device

| Param | Type | Description | | --- | --- | --- | | path | string | BIP32 path (hardened child key), ex: m/44'/784'/0'/0'/0' |

SecuxSUI.resolvePublickey(response) ⇒ string

Resove ed25519 publickey from response data.

Returns: string - ed25519 publickey (hex string)

| Param | Type | Description | | --- | --- | --- | | response | communicationData | data from device |

SecuxSUI.prepareSign(path, content) ⇒ prepared

Prepare data for signing.

Returns: prepared - prepared object

| Param | Type | Description | | --- | --- | --- | | path | string | m/44'/195'/... | | content | transferData | transaction object |

SecuxSUI.resolveSignature(response) ⇒ string

Reslove signatures from response data.

Returns: string - signature (base64 encoded)

| Param | Type | Description | | --- | --- | --- | | response | communicationData | data from device |

SecuxSUI.resolveTransaction(response, params) ⇒ string

Resolve transaction for broadcasting.

Returns: string - signed raw transaction

| Param | Type | Description | | --- | --- | --- | | response | communicationData | data from device | | params | TransactionObject | raw transaction |

transferData : object

Properties

| Name | Type | Description | | --- | --- | --- | | from | string | sending address | | to | string | receiving address | | amount | number | transfer amount | | blockID | string | | | blockNumber | number | | | timestamp | number | | | [feeLimit] | number | | | [expiration] | number | |

prepared : object

Properties

| Name | Type | Description | | --- | --- | --- | | commandData | communicationData | data for sending to device | | rawTx | communicationData | unsigned raw transaction |

© 2018-21 SecuX Technology Inc.

authors: [email protected] --