@nadohq/mobile-client 0.36.0 → 0.37.0

package/src/signing/signing.test.ts

@@ -19,8 +19,8 @@ const FIXED_PRIVATE_KEY =
   '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b786907' as const;
 const FIXED_VERIFYING_ADDR = '0x0000000000000000000000000000000000000001';
 
-// `set_username`, `set_private_mode`, and `register_expo_token` mirror the backend's pinned fixtures in
-// mobile/src/api/types.rs, so a divergence here is a real wire-format break rather than a stale expectation.
+// Every hash here mirrors the backend's pinned fixtures in mobile/src/api/types.rs, so a divergence is a
+// real wire-format break rather than a stale expectation.
 const PINNED_HASHES = {
   set_username:
     '0xb4a55d9eb0be4e5c9457761c0c34c75cf39f7c07bd170700d8dd5e9c7de4a659',
@@ -28,8 +28,20 @@ const PINNED_HASHES = {
     '0x4d12a06234d751e6ddcc01d8f70836bb5b7e207e573641d1efb5aaf2b0f30d10',
   register_expo_token:
     '0x1b9471afc9bde66f9bffd576d3326420e1bade4e16afa3a73ddc65f27155611c',
+  set_follow_true:
+    '0x1ff8529b7c1a0111313eed98536e591555a3bcab51133776ce30c6ef32b559b3',
+  set_follow_false:
+    '0xec9e9e8f32ac4fcf3015f8b7f20c338623ff85db0488703c7fb688519a46e2e5',
+  followers:
+    '0x44f3cd2c991196cf949a25cebe0e16a4e5e8a14846d35751f3931de3c8ffcabd',
+  following:
+    '0xaddabad62abf1919dcd4250eee20359970cbfb59f4c81536551462f8918e5ddd',
 } as const;
 
+// Every follow fixture on the backend targets this subaccount.
+const FIXTURE_TARGET_SUBACCOUNT =
+  '0x1111111111111111111111111111111111111111111111111111111111111111' as const;
+
 describe('[mobile-client]: signing (offline)', () => {
   describe('pinned payload hashes', () => {
     it('set_username', () => {
@@ -61,6 +73,48 @@ describe('[mobile-client]: signing (offline)', () => {
       const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
       expect(hash).toBe(PINNED_HASHES.register_expo_token);
     });
+
+    it('set_follow (follow)', () => {
+      const inner: MobileSignedInner = {
+        type: 'set_follow',
+        subaccount: FIXTURE_TARGET_SUBACCOUNT,
+        is_following: true,
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.set_follow_true);
+    });
+
+    it('set_follow (unfollow)', () => {
+      const inner: MobileSignedInner = {
+        type: 'set_follow',
+        subaccount: FIXTURE_TARGET_SUBACCOUNT,
+        is_following: false,
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.set_follow_false);
+    });
+
+    it('followers', () => {
+      const inner: MobileSignedInner = {
+        type: 'followers',
+        subaccount: FIXTURE_TARGET_SUBACCOUNT,
+        cursor: null,
+        limit: 50,
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.followers);
+    });
+
+    it('following', () => {
+      const inner: MobileSignedInner = {
+        type: 'following',
+        subaccount: FIXTURE_TARGET_SUBACCOUNT,
+        cursor: null,
+        limit: 50,
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.following);
+    });
   });
 
   it('canonicalizes msgpack key order regardless of input key order', () => {
@@ -76,8 +130,8 @@ describe('[mobile-client]: signing (offline)', () => {
   });
 
   it('canonicalizes multi-field key order regardless of input key order', () => {
-    // register_expo_token is the only signed payload with more than one field, so it is where a caller can
-    // actually get the order wrong; canonicalizeMobileInner must rebuild it in the backend's declaration order.
+    // register_expo_token has the most fields of any signed payload, so it is where a caller is most likely
+    // to get the order wrong; canonicalizeMobileInner must rebuild it in the backend's declaration order.
     const outOfOrderInner = {
       app_version: '1.2.3',
       locale: 'en-GB',

package/src/signing/types.ts

@@ -11,6 +11,11 @@ import { MobileNotificationPlatform } from '../types/serverModelTypes';
  * declares its structs — `type` first, then the remaining fields — or the hash won't match and signature
  * verification fails. This type only describes the shape; the authoritative runtime key order is enforced by
  * {@link canonicalizeMobileInner}, which is the source of truth. Keep the field order here in sync with it.
+ *
+ * Every bytes32 field must be lowercase hex. The backend decodes them case-insensitively but hashes its own
+ * re-serialization, which is always lowercase, so a mixed-case value is accepted on the wire and then fails
+ * authentication against a hash the client never reproduced. Build them with `subaccountToHex`, which
+ * lowercases; unlike bytes32, string fields such as `display_name` are hashed as-is and keep their casing.
  */
 export type MobileSignedInner =
   | { type: 'set_username'; display_name: string }
@@ -23,14 +28,42 @@ export type MobileSignedInner =
       // backend, which serializes `Option::None` as nil under the same key.
       locale: string | null;
       app_version: string | null;
+    }
+  | {
+      type: 'set_follow';
+      subaccount: Hex;
+      /** `true` follows the target, `false` unfollows it. Both directions are idempotent. */
+      is_following: boolean;
+    }
+  | {
+      type: 'followers';
+      subaccount: Hex;
+      /** `null` requests the first page; otherwise an opaque cursor from the previous page. */
+      cursor: string | null;
+      /** `null` requests the backend default of 25; otherwise 1–50. */
+      limit: number | null;
+    }
+  | {
+      type: 'following';
+      subaccount: Hex;
+      /** `null` requests the first page; otherwise an opaque cursor from the previous page. */
+      cursor: string | null;
+      /** `null` requests the backend default of 25; otherwise 1–50. */
+      limit: number | null;
     };
 
+/**
+ * The single {@link MobileSignedInner} member carrying the given `type` tag.
+ */
+export type MobileSignedInnerByType<T extends MobileSignedInner['type']> =
+  Extract<MobileSignedInner, { type: T }>;
+
 /**
  * Type-specific payload fields for a signed inner request of a given `type` (the inner payload without its
  * `type` tag). Derived from {@link MobileSignedInner} so the two never drift apart.
  */
 export type MobileSignedInnerParams<T extends MobileSignedInner['type']> = Omit<
-  Extract<MobileSignedInner, { type: T }>,
+  MobileSignedInnerByType<T>,
   'type'
 >;
 

package/src/types/clientTypes.ts

@@ -9,7 +9,11 @@ import {
 
 /**
  * A subaccount's public profile, as returned by an unsigned profile lookup. Private Mode hides the account's
- * activity, not its profile, so `privateMode` is exposed here too.
+ * activity, not its profile, so `privateMode` is exposed here too. A subaccount with no identity row still
+ * yields a profile, with `null` names and `privateMode: false`.
+ *
+ * The last three fields are `undefined` unless the matching {@link MobileProfilesInclude} asked for them —
+ * absent means "not requested" rather than "none".
  */
 export interface MobilePublicProfile {
   subaccount: Hex;
@@ -18,6 +22,80 @@ export interface MobilePublicProfile {
   /** User-facing name as claimed, or `null` if no username has been claimed. */
   displayName: string | null;
   privateMode: boolean;
+  /**
+   * Exact count at query time rather than a cached counter, including unnamed and private accounts — Private
+   * Mode hides activity, not relationships. Requires the `followCounts` include.
+   */
+  followerCount?: number;
+  followingCount?: number;
+  /** Requires the `followSummary` include, and is relative to that include's `viewAs`. */
+  followSummary?: MobileFollowSummary;
+}
+
+/**
+ * The identity fields the backend attaches to a subaccount wherever it surfaces one alongside other data.
+ * Resolved at read time, so a rename shows up on the next read without any change to the surrounding record.
+ */
+export interface MobileIdentitySummary {
+  subaccount: Hex;
+  /** `null` when the account has not claimed a username; render a local fallback label from `subaccount`. */
+  username: string | null;
+  /** `null` when the account has not claimed a username; render a local fallback label from `subaccount`. */
+  displayName: string | null;
+  /** Reserved for a future avatar source; `null` until one is implemented. */
+  avatarUrl: string | null;
+}
+
+/**
+ * A viewer's relationship with one Profile, plus the Followed By preview: accounts the viewer follows that
+ * also follow that Profile. Every preview entry is therefore already familiar to the viewer, which is why it
+ * carries no `isFollowing` of its own.
+ */
+export interface MobileFollowSummary {
+  /** The direct `viewer -> viewed Profile` relationship. */
+  isFollowing: boolean;
+  /** Exact size of the two-edge intersection, independent of how many previews came back. */
+  followedByCount: number;
+  /**
+   * Newest `preview -> viewed Profile` relationship first, with a bytes32 tie-break. Capped at
+   * `MOBILE_FOLLOWED_BY_PREVIEW_LIMIT` (2) by the backend and not client-configurable.
+   */
+  followedBy: MobileIdentitySummary[];
+}
+
+/**
+ * One row of a Followers or Following page.
+ */
+export interface MobileFollowListAccount {
+  identity: MobileIdentitySummary;
+  /**
+   * Whether the *Viewer* follows this account — not the listed relationship that put it in the page. The
+   * Viewer can appear in another Profile's list, and does not follow themself, so their own row is `false`.
+   */
+  isFollowing: boolean;
+  /** This account's own follower count. */
+  followerCount: number;
+}
+
+/**
+ * A page of Followers or Following. Pagination is live rather than snapshot: a Follow or Unfollow between
+ * pages can move an account, so an account can appear twice or not at all across one session. Deduplicate by
+ * {@link MobileIdentitySummary.subaccount} and restart from `cursor: undefined` on refresh.
+ */
+export interface MobileFollowListPage {
+  accounts: MobileFollowListAccount[];
+  /** `null` means the list is complete. */
+  nextCursor: string | null;
+}
+
+/**
+ * Post-commit state of a follow or unfollow. The mutation and its count share one database transaction, so
+ * these values are authoritative — apply them rather than re-reading.
+ */
+export interface MobileFollowMutationResult {
+  isFollowing: boolean;
+  /** The *target's* follower count after the mutation, not the sender's. */
+  followerCount: number;
 }
 
 /**
@@ -43,16 +121,9 @@ export interface MobileFeedMargin {
  * (a rename can change an already-fetched trade on the next read). Amounts are display-oriented human-unit
  * numbers — do not use them for accounting, order construction, or exact threshold decisions.
  */
-export interface MobileFeedTrade {
+export interface MobileFeedTrade extends MobileIdentitySummary {
   /** Order digest this trade is keyed by; the stable id for reconciling live pagination. */
   orderDigest: Hex;
-  subaccount: Hex;
-  /** `null` when the trader has not claimed a username; render a local fallback label from `subaccount`. */
-  username: string | null;
-  /** `null` when the trader has not claimed a username; render a local fallback label from `subaccount`. */
-  displayName: string | null;
-  /** Reserved for a future avatar source; `null` until one is implemented. */
-  avatarUrl: string | null;
   productId: number;
   /** Executed quantity in human units. */
   quantity: number;
@@ -155,9 +226,31 @@ export interface GetMobileUsernameAvailabilityParams {
 }
 
 /**
- * Params for {@link MobileClient.getPublicProfile}.
+ * Opt-in extras for a profiles lookup. Each one adds fields that are otherwise absent from every returned
+ * profile, and costs extra rate-limit weight per profile, so ask only for what the UI shows.
  */
-export type GetMobilePublicProfileParams = Subaccount;
+export interface MobileProfilesInclude {
+  /** Populates `followerCount` and `followingCount`. */
+  followCounts?: boolean;
+  /**
+   * Populates `followSummary`, relative to `viewAs`. Unlike the signed follow list reads, this viewer
+   * identity is an unauthenticated claim — the route takes no signature — so do not treat the result as
+   * proof of who is asking.
+   */
+  followSummary?: { viewAs: Subaccount };
+}
+
+/**
+ * Params for {@link MobileClient.getProfiles}.
+ */
+export interface GetMobileProfilesParams {
+  /**
+   * 1–`MOBILE_PROFILES_MAX_BATCH_SIZE` (25) distinct subaccounts. Duplicates and an empty list are rejected
+   * rather than deduplicated, and results come back in this exact order.
+   */
+  subaccounts: Subaccount[];
+  include?: MobileProfilesInclude;
+}
 
 /**
  * Params for {@link MobileClient.getFeed}.
@@ -192,6 +285,50 @@ export interface MobileSetPrivateModeParams extends MobileSignedRequestParams {
   privateMode: boolean;
 }
 
+/**
+ * Common params for the signed follow requests. The subaccount carried by {@link MobileSignedRequestParams}
+ * is the signing Viewer (the Follower, for mutations); `target` is the other party.
+ */
+export interface MobileFollowRequestParams extends MobileSignedRequestParams {
+  /** The Profile being followed, unfollowed, or read. Must not be the signing subaccount. */
+  target: Subaccount;
+}
+
+/**
+ * Params for {@link MobileClient.setFollow}.
+ */
+export interface MobileSetFollowParams extends MobileFollowRequestParams {
+  /** `true` follows the target, `false` unfollows it. Both directions are idempotent. */
+  isFollowing: boolean;
+}
+
+/**
+ * Common params for a Followers or Following page.
+ */
+export interface GetMobileFollowListParams extends MobileFollowRequestParams {
+  /**
+   * Opaque cursor from the previous page's {@link MobileFollowListPage.nextCursor}. Omit for the first page.
+   * A cursor is bound to its Viewer, Profile, and list direction — reusing it elsewhere fails with
+   * `INVALID_FOLLOW_CURSOR`.
+   */
+  cursor?: string;
+  /**
+   * Page size, 1–`MOBILE_FOLLOW_LIST_MAX_PAGE_SIZE` (50); the backend defaults to
+   * `MOBILE_FOLLOW_LIST_DEFAULT_PAGE_SIZE` (25) when omitted.
+   */
+  limit?: number;
+}
+
+/**
+ * Params for {@link MobileClient.getFollowers}.
+ */
+export type GetMobileFollowersParams = GetMobileFollowListParams;
+
+/**
+ * Params for {@link MobileClient.getFollowing}.
+ */
+export type GetMobileFollowingParams = GetMobileFollowListParams;
+
 /**
  * Params for {@link MobileClient.registerExpoToken}.
  */

package/src/types/mobileErrorCodes.ts

@@ -13,6 +13,18 @@ export const MOBILE_ERROR_CODES = {
   /** Another identity write for the subaccount committed with a later nonce. Re-read before retrying. */
   STALE_IDENTITY_UPDATE: 6105,
   PROFILE_NOT_FOUND: 6106,
+  /** Profiles lookup is empty, holds duplicates, or exceeds the batch maximum. Do not retry unchanged. */
+  INVALID_PROFILES_REQUEST: 6107,
+  /** Follow mutation names the same source and target, or an isolated participant. Do not retry unchanged. */
+  INVALID_FOLLOW_TARGET: 6110,
+  /** Signed follower is not yet in the canonical Query DB subaccount index. Retry after index catch-up. */
+  FOLLOWER_NOT_ELIGIBLE: 6111,
+  /** Follow target is not yet in the canonical Query DB subaccount index. Refresh after a new record. */
+  FOLLOWING_NOT_FOUND: 6112,
+  /** Follow list cursor is malformed or bound to a different list request. Restart from `cursor: null`. */
+  INVALID_FOLLOW_CURSOR: 6113,
+  /** A follow list or followed-by limit is outside its accepted range. Fix it; do not retry unchanged. */
+  INVALID_FOLLOW_LIMIT: 6114,
   INVALID_EXPO_TOKEN: 6200,
   INVALID_DEVICE_METADATA: 6201,
   INVALID_PREFERENCES: 6202,

package/src/types/serverExecuteTypes.ts

@@ -3,6 +3,7 @@ import {
   MobileServerSuccessResponse,
 } from './serverBaseTypes';
 import {
+  MobileServerExecuteRequestType,
   MobileServerPublicExecuteRequestByType,
   MobileServerPublicExecuteRequestType,
 } from './serverRequestTypes';
@@ -21,8 +22,45 @@ export type MobileServerPublicExecuteRequest<
 }[T];
 
 /**
- * Discriminated `execute` result union. Mobile execute routes return no payload beyond the success
- * discriminant, so the success arm is the base success envelope; failures use the uniform failure envelope.
+ * Payload the `set_follow` execute returns alongside the success envelope. The mutation and the count commit
+ * in one database transaction, so these are the authoritative post-mutation values — prefer them over
+ * re-reading, and note that overlapping toggles for the same pair can respond out of arrival order.
+ */
+export interface MobileServerFollowMutationResponse {
+  is_following: boolean;
+  /** The *target's* follower count after the mutation, not the sender's. */
+  follower_count: number;
+}
+
+/**
+ * Payload of an execute route that returns nothing beyond the success discriminant. Spelled `Record<never,
+ * never>` rather than `Record<string, never>` because the latter's index signature would collapse `status` to
+ * `never` when intersected with the success envelope.
+ */
+export type MobileServerEmptyExecuteResponse = Record<never, never>;
+
+/**
+ * Success payloads for each signed `execute`, keyed by request `type`. Most execute routes carry no payload
+ * beyond the success discriminant and so map to an empty object; `set_follow` returns its post-commit
+ * relationship state.
+ */
+export interface MobileServerExecuteResponseByType {
+  set_username: MobileServerEmptyExecuteResponse;
+  set_private_mode: MobileServerEmptyExecuteResponse;
+  register_expo_token: MobileServerEmptyExecuteResponse;
+  set_follow: MobileServerFollowMutationResponse;
+}
+
+/**
+ * Full success response for a signed `execute`: the {@link MobileServerSuccessResponse} envelope with the
+ * route's payload inlined alongside `status`, matching how the query routes inline theirs.
+ */
+export type MobileServerExecuteSuccessResponse<
+  T extends MobileServerExecuteRequestType = MobileServerExecuteRequestType,
+> = MobileServerSuccessResponse & MobileServerExecuteResponseByType[T];
+
+/**
+ * Discriminated `execute` result union used at the transport boundary, before the envelope is narrowed.
  */
 export type MobileServerExecuteResult =
   | MobileServerSuccessResponse

package/src/types/serverModelTypes.ts

@@ -18,14 +18,66 @@ export type MobileNotificationCategory =
   | 'announcement';
 
 /**
- * Server-side public profile shape (snake_case). Name fields are `null` until the subaccount claims a
- * username.
+ * Server-side identity summary (snake_case): the read-time identity fields the backend attaches to a
+ * subaccount wherever it surfaces one alongside other data. Name fields are `null` until the subaccount
+ * claims a username, and a rename shows up on the next read without any change to the surrounding record.
+ */
+export interface MobileServerIdentitySummary {
+  subaccount: Hex;
+  username: string | null;
+  display_name: string | null;
+  /** Reserved for a future avatar source; `null` until one is implemented. */
+  avatar_url: string | null;
+}
+
+/**
+ * Server-side follow summary (snake_case), nested in a `profiles` entry when the `follow_summary` include is
+ * requested. `is_following` is the direct `view_as -> this profile` relationship; every `followed_by` entry
+ * satisfies both `view_as -> entry` and `entry -> this profile`, so each one is already familiar to the
+ * viewer and carries no `is_following` of its own.
+ */
+export interface MobileServerFollowSummary {
+  is_following: boolean;
+  /** Exact size of the two-edge intersection, independent of how many previews came back. */
+  followed_by_count: number;
+  /** Capped at `MOBILE_FOLLOWED_BY_PREVIEW_LIMIT` (2) by the backend; not client-configurable. */
+  followed_by: MobileServerIdentitySummary[];
+}
+
+/**
+ * Server-side public profile shape (snake_case), shared by the singular `profile` and batched `profiles`
+ * queries. Name fields are `null` until the subaccount claims a username; a subaccount with no identity row
+ * still yields an entry, with `null` names and `private_mode: false`.
+ *
+ * The three optional fields are omitted from the wire entirely unless the matching `profiles` include asked
+ * for them, which is why they are optional rather than nullable — absent means "not requested", not "none".
+ * The singular `profile` query never returns any of them.
  */
 export interface MobileServerProfile {
   subaccount: Hex;
   username: string | null;
   display_name: string | null;
   private_mode: boolean;
+  /**
+   * Exact count at query time — the backend counts rather than reading a cached counter. Unnamed and private
+   * accounts are included: Private Mode hides activity, not relationships. Requires `follow_counts`.
+   */
+  follower_count?: number;
+  following_count?: number;
+  /** Requires the `follow_summary` include, and is relative to that include's `view_as`. */
+  follow_summary?: MobileServerFollowSummary;
+}
+
+/**
+ * Server-side row of a Followers or Following page (snake_case). `is_following` describes the *Viewer's*
+ * relationship to this account, not the listed relationship that put it in the page, so it is `false` on the
+ * Viewer's own row.
+ */
+export interface MobileServerFollowListAccount {
+  identity: MobileServerIdentitySummary;
+  is_following: boolean;
+  /** The listed account's own follower count, exact at query time. */
+  follower_count: number;
 }
 
 /**
@@ -97,14 +149,9 @@ export interface MobileServerFeedMargin {
  * trader's current identity. Amounts are display-oriented human-unit JSON numbers — do not use them for
  * accounting, order construction, or exact threshold decisions.
  */
-export interface MobileServerFeedTrade {
+export interface MobileServerFeedTrade extends MobileServerIdentitySummary {
   /** Order digest this row is keyed by; the stable id clients use to reconcile live pagination. */
   order_digest: Hex;
-  subaccount: Hex;
-  username: string | null;
-  display_name: string | null;
-  /** Reserved for a future avatar source; `null` until one is implemented. */
-  avatar_url: string | null;
   product_id: number;
   /** Executed quantity in human units. */
   quantity: number;

package/src/types/serverQueryTypes.ts

@@ -3,12 +3,14 @@ import { MobileServerSuccessResponse } from './serverBaseTypes';
 import {
   MobileNotificationPlatform,
   MobileServerFeedTrade,
+  MobileServerFollowListAccount,
   MobileServerNotificationPreferences,
   MobileServerProfile,
 } from './serverModelTypes';
 import {
   MobileServerPublicQueryRequestByType,
   MobileServerPublicQueryRequestType,
+  MobileServerSignedQueryRequestType,
 } from './serverRequestTypes';
 
 /**
@@ -32,10 +34,11 @@ export interface MobileServerUsernameAvailabilityResponse {
 }
 
 /**
- * Payload of the `profile` public query success response.
+ * Payload of the `profiles` public query success response. One entry per requested subaccount, in the exact
+ * order they were requested, so callers can correlate positionally as well as by `subaccount`.
  */
-export interface MobileServerProfileResponse {
-  profile: MobileServerProfile;
+export interface MobileServerProfilesResponse {
+  profiles: MobileServerProfile[];
 }
 
 /**
@@ -79,7 +82,7 @@ export interface MobileServerRegisteredWalletResponse {
  */
 export interface MobileServerPublicQueryResponseByType {
   username_availability: MobileServerUsernameAvailabilityResponse;
-  profile: MobileServerProfileResponse;
+  profiles: MobileServerProfilesResponse;
   feed: MobileServerFeedResponse;
   notification_preferences: MobileServerNotificationPreferencesResponse;
   registered_wallet: MobileServerRegisteredWalletResponse;
@@ -94,3 +97,31 @@ export type MobileServerPublicQuerySuccessResponse<
   T extends MobileServerPublicQueryRequestType =
     MobileServerPublicQueryRequestType,
 > = MobileServerSuccessResponse & MobileServerPublicQueryResponseByType[T];
+
+/**
+ * Payload of the `followers` and `following` signed query success responses. Both list directions share one
+ * shape; only the relationship that selected the rows differs.
+ */
+export interface MobileServerFollowListResponse {
+  accounts: MobileServerFollowListAccount[];
+  /** `null` means the list is complete. */
+  next_cursor: string | null;
+}
+
+/**
+ * Success payloads for each signed `query`, keyed by request `type` — the signed counterpart to
+ * {@link MobileServerPublicQueryResponseByType}.
+ */
+export interface MobileServerSignedQueryResponseByType {
+  followers: MobileServerFollowListResponse;
+  following: MobileServerFollowListResponse;
+}
+
+/**
+ * Full success response for a signed `query`: the {@link MobileServerSuccessResponse} envelope with the
+ * query's payload inlined alongside `status`.
+ */
+export type MobileServerSignedQuerySuccessResponse<
+  T extends MobileServerSignedQueryRequestType =
+    MobileServerSignedQueryRequestType,
+> = MobileServerSuccessResponse & MobileServerSignedQueryResponseByType[T];

package/src/types/serverRequestTypes.ts

@@ -2,12 +2,34 @@ import { Hex } from 'viem';
 import { MobileSignedInner } from '../signing/types';
 import { MobileServerNotificationPreferences } from './serverModelTypes';
 
+/**
+ * Opt-in extras for a `profiles` query. Each one costs extra rate-limit weight per profile and adds fields
+ * that are otherwise absent from the response, so the backend gates them behind an explicit request rather
+ * than always resolving the follow graph on a public route.
+ */
+export interface MobileServerProfilesInclude {
+  /** Adds `follower_count` and `following_count` to every entry. Omitted or `false` leaves both absent. */
+  follow_counts?: boolean;
+  /**
+   * Adds `follow_summary` to every entry, relative to the `view_as` subaccount. Unlike the signed follow
+   * list reads, `view_as` is an unauthenticated claim on this public route.
+   */
+  follow_summary?: { view_as: Hex };
+}
+
 /**
  * Params for each unsigned `public_query`, keyed by request `type`.
  */
 export interface MobileServerPublicQueryRequestByType {
   username_availability: { display_name: string };
-  profile: { subaccount: Hex };
+  profiles: {
+    /**
+     * 1–`MOBILE_PROFILES_MAX_BATCH_SIZE` (25) distinct subaccounts. Results come back in this exact order,
+     * one entry per request slot.
+     */
+    subaccounts: Hex[];
+    include?: MobileServerProfilesInclude;
+  };
   feed: {
     /**
      * Minimum notional as a whole-dollar JSON integer (NOT an x18 string), at least $1,000. Omitted or
@@ -52,18 +74,31 @@ export interface MobileServerPublicExecuteRequestByType {
 export type MobileServerPublicExecuteRequestType =
   keyof MobileServerPublicExecuteRequestByType;
 
+/**
+ * Discriminant `type` values for signed `query` requests: the read-only subset of {@link MobileSignedInner}
+ * tags. Unlike the public queries, these carry no separate params map — a signed request body *is* its inner
+ * payload flattened with the envelope, so {@link MobileSignedInner} is the single source of truth for both
+ * the fields and their significant order.
+ */
+export type MobileServerSignedQueryRequestType = 'followers' | 'following';
+
 /**
  * Discriminant `type` values for signed `execute` requests: the write subset of {@link MobileSignedInner}
- * tags. With no signed queries remaining, every signed inner type is an execute.
+ * tags, i.e. everything that is not a signed query.
  */
-export type MobileServerExecuteRequestType = MobileSignedInner['type'];
+export type MobileServerExecuteRequestType = Exclude<
+  MobileSignedInner['type'],
+  MobileServerSignedQueryRequestType
+>;
 
 /**
  * Wire `request_type` the backend echoes on failure envelopes, prefixed by the route that produced it:
- * `public_query_*` for unsigned queries, `public_execute_*` for unsigned writes, and `execute_*` for signed
- * writes (e.g. `execute_set_username`).
+ * `public_query_*` for unsigned queries, `public_execute_*` for unsigned writes, `execute_*` for signed
+ * writes (e.g. `execute_set_username`), and `query_*` for signed reads (e.g. `query_followers`). The prefix
+ * names the route, so it never carries the `mobile:` prefix that the EIP-712 method does.
  */
 export type MobileServerRequestType =
   | `public_query_${MobileServerPublicQueryRequestType}`
   | `public_execute_${MobileServerPublicExecuteRequestType}`
-  | `execute_${MobileServerExecuteRequestType}`;
+  | `execute_${MobileServerExecuteRequestType}`
+  | `query_${MobileServerSignedQueryRequestType}`;

package/src/utils/follow.ts

@@ -0,0 +1,22 @@
+/**
+ * Maximum Followers/Following page size the backend accepts. Requests outside 1–50 fail with
+ * `INVALID_FOLLOW_LIMIT`.
+ */
+export const MOBILE_FOLLOW_LIST_MAX_PAGE_SIZE = 50;
+
+/**
+ * Page size the backend uses when `limit` is omitted from a Followers or Following request.
+ */
+export const MOBILE_FOLLOW_LIST_DEFAULT_PAGE_SIZE = 25;
+
+/**
+ * Number of Followed By preview identities a follow summary carries. Fixed by the backend rather than
+ * requested, so use it to size the preview UI; `followedByCount` still reports the full intersection.
+ */
+export const MOBILE_FOLLOWED_BY_PREVIEW_LIMIT = 2;
+
+/**
+ * Maximum number of subaccounts a single profiles lookup accepts. An empty list, a duplicate, or more than
+ * this many fail with `INVALID_PROFILES_REQUEST`.
+ */
+export const MOBILE_PROFILES_MAX_BATCH_SIZE = 25;

package/src/utils/index.ts

@@ -1,3 +1,4 @@
 export * from './feed';
+export * from './follow';
 export * from './patterns';
 export * from './serverResponseGuards';