@zoguxprotocol/client-js 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zoguxprotocol/client-js",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "General client library for the new Zogux system (v4 decentralized)",
   "main": "build/cjs/src/index.js",
   "module": "build/esm/src/index.js",
@@ -55,7 +55,7 @@
     "@osmonauts/lcd": "^0.6.0",
     "@scure/bip32": "^1.1.5",
     "@scure/bip39": "^1.1.1",
-    "@zoguxprotocol/proto": "0.1.6",
+    "@zoguxprotocol/proto": "0.1.7",
     "axios": "1.1.3",
     "bech32": "^1.1.4",
     "bignumber.js": "^9.1.1",

package/src/clients/constants.ts

@@ -101,6 +101,11 @@ export const TYPE_URL_MSG_CREATE_TRANSFER = '/zogux.sending.MsgCreateTransfer';
 export const TYPE_URL_MSG_WITHDRAW_FROM_SUBACCOUNT =
   '/zogux.sending.MsgWithdrawFromSubaccount';
 export const TYPE_URL_MSG_DEPOSIT_TO_SUBACCOUNT = '/zogux.sending.MsgDepositToSubaccount';
+export const TYPE_URL_MSG_TRANSFER_SPOT_TO_PERP = '/zogux.sending.MsgTransferSpotToPerp';
+export const TYPE_URL_MSG_TRANSFER_PERP_TO_SPOT = '/zogux.sending.MsgTransferPerpToSpot';
+export const TYPE_URL_MSG_CREATE_TRANSFER_SPOT = '/zogux.sending.MsgCreateTransferSpot';
+export const TYPE_URL_MSG_DEPOSIT_TO_SPOT = '/zogux.sending.MsgDepositToSpot';
+export const TYPE_URL_MSG_WITHDRAW_FROM_SPOT = '/zogux.sending.MsgWithdrawFromSpot';
 
 // x/affiliates
 export const TYPE_URL_MSG_REGISTER_AFFILIATE = '/zogux.affiliates.MsgRegisterAffiliate';

package/src/clients/lib/registry.ts

@@ -16,8 +16,12 @@ import { MsgCreateOracleMarket } from '@zoguxprotocol/proto/src/codegen/zogux/pr
 import {
   MsgWithdrawFromSubaccount,
   MsgDepositToSubaccount,
+  MsgTransferSpotToPerp,
+  MsgTransferPerpToSpot,
+  MsgCreateTransferSpot,
+  MsgDepositToSpot,
+  MsgWithdrawFromSpot,
 } from '@zoguxprotocol/proto/src/codegen/zogux/sending/transfer';
-import { MsgCreateTransfer } from '@zoguxprotocol/proto/src/codegen/zogux/sending/tx';
 import {
   MsgDepositToMegavault,
   MsgWithdrawFromMegavault,
@@ -34,6 +38,11 @@ import {
   TYPE_URL_MSG_CREATE_TRANSFER,
   TYPE_URL_MSG_WITHDRAW_FROM_SUBACCOUNT,
   TYPE_URL_MSG_DEPOSIT_TO_SUBACCOUNT,
+  TYPE_URL_MSG_TRANSFER_SPOT_TO_PERP,
+  TYPE_URL_MSG_TRANSFER_PERP_TO_SPOT,
+  TYPE_URL_MSG_CREATE_TRANSFER_SPOT,
+  TYPE_URL_MSG_DEPOSIT_TO_SPOT,
+  TYPE_URL_MSG_WITHDRAW_FROM_SPOT,
   TYPE_URL_BATCH_CANCEL,
   TYPE_URL_MSG_DEPOSIT_TO_MEGAVAULT,
   TYPE_URL_MSG_WITHDRAW_FROM_MEGAVAULT,
@@ -42,6 +51,7 @@ import {
   TYPE_URL_MSG_ADD_AUTHENTICATOR,
   TYPE_URL_MSG_REMOVE_AUTHENTICATOR,
 } from '../constants';
+import { MsgCreateTransfer } from '../types';
 
 export const registry: ReadonlyArray<[string, GeneratedType]> = [];
 export function generateRegistry(): Registry {
@@ -73,6 +83,11 @@ export function generateRegistry(): Registry {
     [TYPE_URL_MSG_CREATE_TRANSFER, MsgCreateTransfer as GeneratedType],
     [TYPE_URL_MSG_WITHDRAW_FROM_SUBACCOUNT, MsgWithdrawFromSubaccount as GeneratedType],
     [TYPE_URL_MSG_DEPOSIT_TO_SUBACCOUNT, MsgDepositToSubaccount as GeneratedType],
+    [TYPE_URL_MSG_TRANSFER_SPOT_TO_PERP, MsgTransferSpotToPerp as GeneratedType],
+    [TYPE_URL_MSG_TRANSFER_PERP_TO_SPOT, MsgTransferPerpToSpot as GeneratedType],
+    [TYPE_URL_MSG_CREATE_TRANSFER_SPOT, MsgCreateTransferSpot as GeneratedType],
+    [TYPE_URL_MSG_DEPOSIT_TO_SPOT, MsgDepositToSpot as GeneratedType],
+    [TYPE_URL_MSG_WITHDRAW_FROM_SPOT, MsgWithdrawFromSpot as GeneratedType],
 
     // affiliates
     [TYPE_URL_MSG_REGISTER_AFFILIATE, MsgRegisterAffiliate as GeneratedType],

package/src/clients/modules/account.ts

@@ -70,6 +70,23 @@ export default class AccountClient extends RestClient {
     });
   }
 
+  /**
+   * Spot asset positions (spot balance per subaccount/asset).
+   * Use for display and validation when building Spot→Perp or Perp→Spot transfers.
+   */
+  async getSpotAssetPositions(
+    address: string,
+    subaccountNumber: number,
+    limit?: number | null,
+  ): Promise<Data> {
+    const uri = '/v4/spotAssetPositions';
+    return this.get(uri, {
+      address,
+      subaccountNumber,
+      limit,
+    });
+  }
+
   // ------ Transfers ------ //
 
   async getTransfersBetween(

package/src/clients/modules/composer.ts

@@ -45,6 +45,11 @@ import {
   TYPE_URL_MSG_CREATE_TRANSFER,
   TYPE_URL_MSG_WITHDRAW_FROM_SUBACCOUNT,
   TYPE_URL_MSG_DEPOSIT_TO_SUBACCOUNT,
+  TYPE_URL_MSG_TRANSFER_SPOT_TO_PERP,
+  TYPE_URL_MSG_TRANSFER_PERP_TO_SPOT,
+  TYPE_URL_MSG_CREATE_TRANSFER_SPOT,
+  TYPE_URL_MSG_DEPOSIT_TO_SPOT,
+  TYPE_URL_MSG_WITHDRAW_FROM_SPOT,
   TYPE_URL_MSG_DELEGATE,
   TYPE_URL_MSG_UNDELEGATE,
   TYPE_URL_MSG_WITHDRAW_DELEGATOR_REWARD,
@@ -338,6 +343,84 @@ export class Composer {
     };
   }
 
+  public composeMsgTransferSpotToPerp(
+    senderAddress: string,
+    senderSubaccountNumber: number,
+    recipientOwner: string,
+    recipientSubaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+  ): EncodeObject {
+    const senderSubaccountId: SubaccountId = { owner: senderAddress, number: senderSubaccountNumber };
+    const recipientSubaccountId: SubaccountId = { owner: recipientOwner, number: recipientSubaccountNumber };
+    return {
+      typeUrl: TYPE_URL_MSG_TRANSFER_SPOT_TO_PERP,
+      value: {
+        sender: senderAddress,
+        senderSubaccountId,
+        recipientSubaccountId,
+        assetId,
+        quantums,
+      },
+    };
+  }
+
+  public composeMsgTransferPerpToSpot(
+    senderAddress: string,
+    senderSubaccountNumber: number,
+    recipientOwner: string,
+    recipientSubaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+  ): EncodeObject {
+    const senderSubaccountId: SubaccountId = { owner: senderAddress, number: senderSubaccountNumber };
+    const recipientSubaccountId: SubaccountId = { owner: recipientOwner, number: recipientSubaccountNumber };
+    return {
+      typeUrl: TYPE_URL_MSG_TRANSFER_PERP_TO_SPOT,
+      value: {
+        sender: senderAddress,
+        senderSubaccountId,
+        recipientSubaccountId,
+        assetId,
+        quantums,
+      },
+    };
+  }
+
+  public composeMsgCreateTransferSpot(
+    senderAddress: string,
+    senderSubaccountNumber: number,
+    recipientOwner: string,
+    recipientSubaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+  ): EncodeObject {
+    const senderSubaccountId: SubaccountId = { owner: senderAddress, number: senderSubaccountNumber };
+    const recipientSubaccountId: SubaccountId = { owner: recipientOwner, number: recipientSubaccountNumber };
+    return { typeUrl: TYPE_URL_MSG_CREATE_TRANSFER_SPOT, value: { sender: senderAddress, senderSubaccountId, recipientSubaccountId, assetId, quantums } };
+  }
+
+  public composeMsgDepositToSpot(
+    address: string,
+    subaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+  ): EncodeObject {
+    const recipient: SubaccountId = { owner: address, number: subaccountNumber };
+    return { typeUrl: TYPE_URL_MSG_DEPOSIT_TO_SPOT, value: { sender: address, recipient, assetId, quantums } };
+  }
+
+  public composeMsgWithdrawFromSpot(
+    address: string,
+    subaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+    recipient: string = address,
+  ): EncodeObject {
+    const sender: SubaccountId = { owner: address, number: subaccountNumber };
+    return { typeUrl: TYPE_URL_MSG_WITHDRAW_FROM_SPOT, value: { sender, recipient, assetId, quantums } };
+  }
+
   // ------------ x/bank ------------
   public composeMsgSendToken(
     address: string,

package/src/clients/modules/post.ts

@@ -43,6 +43,11 @@ import {
 protobuf.util.Long = Long;
 protobuf.configure();
 
+/**
+ * Post signs and broadcasts transactions. All messages are built via this.composer;
+ * when adding a new message type, follow: constants (TYPE_URL) → lib/registry.ts →
+ * composer.composeMsg* → Post method that calls composer and passes to send().
+ */
 export class Post {
   public readonly composer: Composer;
   private readonly registry: Registry;
@@ -757,6 +762,147 @@ export class Post {
     });
   }
 
+  async transferSpotToPerp(
+    subaccount: SubaccountInfo,
+    recipientOwner: string,
+    recipientSubaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+    broadcastMode?: BroadcastMode,
+  ): Promise<BroadcastTxAsyncResponse | BroadcastTxSyncResponse | IndexedTx> {
+    const msg = await this.transferSpotToPerpMsg(
+      subaccount.address,
+      subaccount.subaccountNumber,
+      recipientOwner,
+      recipientSubaccountNumber,
+      assetId,
+      quantums,
+    );
+    return this.send(subaccount, () => Promise.resolve([msg]), false, undefined, undefined, broadcastMode);
+  }
+
+  async transferSpotToPerpMsg(
+    senderAddress: string,
+    senderSubaccountNumber: number,
+    recipientOwner: string,
+    recipientSubaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+  ): Promise<EncodeObject> {
+    return Promise.resolve(
+      this.composer.composeMsgTransferSpotToPerp(
+        senderAddress,
+        senderSubaccountNumber,
+        recipientOwner,
+        recipientSubaccountNumber,
+        assetId,
+        quantums,
+      ),
+    );
+  }
+
+  async transferPerpToSpot(
+    subaccount: SubaccountInfo,
+    recipientOwner: string,
+    recipientSubaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+    broadcastMode?: BroadcastMode,
+  ): Promise<BroadcastTxAsyncResponse | BroadcastTxSyncResponse | IndexedTx> {
+    const msg = await this.transferPerpToSpotMsg(
+      subaccount.address,
+      subaccount.subaccountNumber,
+      recipientOwner,
+      recipientSubaccountNumber,
+      assetId,
+      quantums,
+    );
+    return this.send(subaccount, () => Promise.resolve([msg]), false, undefined, undefined, broadcastMode);
+  }
+
+  async transferPerpToSpotMsg(
+    senderAddress: string,
+    senderSubaccountNumber: number,
+    recipientOwner: string,
+    recipientSubaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+  ): Promise<EncodeObject> {
+    return Promise.resolve(
+      this.composer.composeMsgTransferPerpToSpot(
+        senderAddress,
+        senderSubaccountNumber,
+        recipientOwner,
+        recipientSubaccountNumber,
+        assetId,
+        quantums,
+      ),
+    );
+  }
+
+  async createTransferSpot(
+    subaccount: SubaccountInfo,
+    recipientOwner: string,
+    recipientSubaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+    broadcastMode?: BroadcastMode,
+  ): Promise<BroadcastTxAsyncResponse | BroadcastTxSyncResponse | IndexedTx> {
+    const msg = await this.createTransferSpotMsg(subaccount.address, subaccount.subaccountNumber, recipientOwner, recipientSubaccountNumber, assetId, quantums);
+    return this.send(subaccount, () => Promise.resolve([msg]), false, undefined, undefined, broadcastMode);
+  }
+
+  async createTransferSpotMsg(
+    senderAddress: string,
+    senderSubaccountNumber: number,
+    recipientOwner: string,
+    recipientSubaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+  ): Promise<EncodeObject> {
+    return Promise.resolve(this.composer.composeMsgCreateTransferSpot(senderAddress, senderSubaccountNumber, recipientOwner, recipientSubaccountNumber, assetId, quantums));
+  }
+
+  async depositToSpot(
+    subaccount: SubaccountInfo,
+    assetId: number,
+    quantums: Long,
+    broadcastMode?: BroadcastMode,
+  ): Promise<BroadcastTxAsyncResponse | BroadcastTxSyncResponse | IndexedTx> {
+    const msg = await this.depositToSpotMsg(subaccount.address, subaccount.subaccountNumber, assetId, quantums);
+    return this.send(subaccount, () => Promise.resolve([msg]), false, undefined, undefined, broadcastMode);
+  }
+
+  async depositToSpotMsg(
+    address: string,
+    subaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+  ): Promise<EncodeObject> {
+    return Promise.resolve(this.composer.composeMsgDepositToSpot(address, subaccountNumber, assetId, quantums));
+  }
+
+  async withdrawFromSpot(
+    subaccount: SubaccountInfo,
+    assetId: number,
+    quantums: Long,
+    recipient?: string,
+    broadcastMode?: BroadcastMode,
+  ): Promise<BroadcastTxAsyncResponse | BroadcastTxSyncResponse | IndexedTx> {
+    const msg = await this.withdrawFromSpotMsg(subaccount.address, subaccount.subaccountNumber, assetId, quantums, recipient);
+    return this.send(subaccount, () => Promise.resolve([msg]), false, undefined, undefined, broadcastMode);
+  }
+
+  async withdrawFromSpotMsg(
+    address: string,
+    subaccountNumber: number,
+    assetId: number,
+    quantums: Long,
+    recipient?: string,
+  ): Promise<EncodeObject> {
+    return Promise.resolve(this.composer.composeMsgWithdrawFromSpot(address, subaccountNumber, assetId, quantums, recipient));
+  }
+
   async sendToken(
     subaccount: SubaccountInfo,
     recipient: string,

package/src/clients/types.ts

@@ -188,4 +188,13 @@ export type GovAddNewMarketParams = {
   delayBlocks: number;
 };
 
+/** Payload shape for MsgTransferSpotToPerp and MsgTransferPerpToSpot (spot–perp transfer). */
+export interface ISpotPerpTransferMessage {
+  sender: string;
+  senderSubaccountId: { owner: string; number: number };
+  recipientSubaccountId: { owner: string; number: number };
+  assetId: number;
+  quantums: Long | bigint;
+}
+
 export * from './modules/proto-includes';

package/src/lib/validation.ts

@@ -8,6 +8,7 @@ import {
   ICancelOrder,
   IPlaceOrder,
   IBatchCancelOrder,
+  ISpotPerpTransferMessage,
 } from '../clients/types';
 import { UserError } from './errors';
 
@@ -145,6 +146,67 @@ export function validateTransferMessage(transfer: Transfer): UserError | undefin
   return undefined;
 }
 
+/**
+ * Validates fields for MsgTransferSpotToPerp / MsgTransferPerpToSpot (spot–perp transfer).
+ * Checks: quantums > 0, subaccount numbers in range, sender and subaccount owners are valid Bech32.
+ */
+function validateSpotPerpTransferMessage(
+  msg: ISpotPerpTransferMessage,
+): UserError | undefined {
+  if (!verifySubaccountNumber(msg.senderSubaccountId?.number ?? -1)) {
+    return new UserError(
+      `senderSubaccountNumber: ${msg.senderSubaccountId?.number ?? 'missing'} cannot be < 0 or > ${MAX_SUBACCOUNT_NUMBER}`,
+    );
+  }
+  if (!verifySubaccountNumber(msg.recipientSubaccountId?.number ?? -1)) {
+    return new UserError(
+      `recipientSubaccountNumber: ${msg.recipientSubaccountId?.number ?? 'missing'} cannot be < 0 or > ${MAX_SUBACCOUNT_NUMBER}`,
+    );
+  }
+  const quantumsZero =
+    typeof msg.quantums === 'bigint'
+      ? msg.quantums <= BigInt(0)
+      : msg.quantums.lessThanOrEqual(Long.ZERO);
+  if (quantumsZero) {
+    return new UserError(`quantums: ${msg.quantums} cannot be <= 0`);
+  }
+  const senderError = verifyIsBech32(msg.sender);
+  if (senderError !== undefined) {
+    return new UserError(senderError.toString());
+  }
+  const senderOwner = msg.senderSubaccountId?.owner;
+  if (senderOwner !== undefined) {
+    const err = verifyIsBech32(senderOwner);
+    if (err !== undefined) return new UserError(err.toString());
+  }
+  const recipientOwner = msg.recipientSubaccountId?.owner;
+  if (recipientOwner !== undefined) {
+    const err = verifyIsBech32(recipientOwner);
+    if (err !== undefined) return new UserError(err.toString());
+  }
+  return undefined;
+}
+
+/**
+ * @describe validateTransferSpotToPerpMessage validates that a Spot→Perp transfer message has
+ *  fields that would be valid on-chain.
+ */
+export function validateTransferSpotToPerpMessage(
+  msg: ISpotPerpTransferMessage,
+): UserError | undefined {
+  return validateSpotPerpTransferMessage(msg);
+}
+
+/**
+ * @describe validateTransferPerpToSpotMessage validates that a Perp→Spot transfer message has
+ *  fields that would be valid on-chain.
+ */
+export function validateTransferPerpToSpotMessage(
+  msg: ISpotPerpTransferMessage,
+): UserError | undefined {
+  return validateSpotPerpTransferMessage(msg);
+}
+
 function verifyGoodTilBlock(goodTilBlock: number | undefined): boolean {
   if (goodTilBlock === undefined) {
     return false;