@farcaster/snap 2.9.0 → 2.10.0

package/src/react-native/snap-view-core.tsx

@@ -1,4 +1,5 @@
 import type { Spec } from "@json-render/core";
+import { createStateStore } from "@json-render/react-native";
 import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
 import { SnapCatalogView } from "./catalog-renderer";
 import { ConfettiOverlay } from "./confetti-overlay";
@@ -21,10 +22,11 @@ import {
   type PaletteColor,
 } from "@farcaster/snap";
 import {
-  applyStatePaths,
+  buildActionActivityStateChanges,
   buildInitialRenderState,
   cloneSnapRenderState,
   getUnpresentedSnapEffects,
+  hasPendingSnapAction,
   markSnapEffectsPresented,
   type SnapRenderState,
 } from "../render-state";
@@ -40,6 +42,12 @@ function optionalString(value: unknown): string | undefined {
   return value ? String(value) : undefined;
 }
 
+function recordValue(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
 function withDefaultElementProps(spec: Spec): Spec {
   if (!spec || typeof spec !== "object" || !("elements" in spec)) return spec;
   const elements = spec.elements as unknown as Record<
@@ -114,12 +122,34 @@ export function SnapViewCoreInner({
     [initialRenderState, spec.state, snap.theme?.accent],
   );
 
+  const stateStore = useMemo(() => createStateStore(initialState), [
+    initialState,
+  ]);
   const stateRef = useRef<Record<string, unknown>>(initialState);
+  const onRenderStateChangeRef = useRef(onRenderStateChange);
+  const pendingActionCountRef = useRef(0);
+  const [hasPendingAction, setHasPendingAction] = useState(false);
+  const [actionActivityVersion, setActionActivityVersion] = useState(0);
 
   useEffect(() => {
     stateRef.current = cloneSnapRenderState(initialState);
   }, [initialState]);
 
+  useEffect(() => {
+    onRenderStateChangeRef.current = onRenderStateChange;
+  }, [onRenderStateChange]);
+
+  useEffect(
+    () =>
+      stateStore.subscribe(() => {
+        const snapshot = cloneSnapRenderState(stateStore.getSnapshot());
+        stateRef.current = snapshot;
+        setHasPendingAction(hasPendingSnapAction(snapshot));
+        onRenderStateChangeRef.current?.(snapshot);
+      }),
+    [stateStore],
+  );
+
   useEffect(() => {
     const catalogResult = snapJsonRenderCatalog.validate(spec);
     if (!catalogResult.success) {
@@ -144,10 +174,6 @@ export function SnapViewCoreInner({
     confetti: 0,
     fireworks: 0,
   });
-  const onRenderStateChangeRef = useRef(onRenderStateChange);
-  useEffect(() => {
-    onRenderStateChangeRef.current = onRenderStateChange;
-  }, [onRenderStateChange]);
   useEffect(() => {
     const effectsToPresent = getUnpresentedSnapEffects(
       stateRef.current,
@@ -169,7 +195,10 @@ export function SnapViewCoreInner({
     }
 
     if (markSnapEffectsPresented(stateRef.current, effectsToPresent)) {
-      onRenderStateChangeRef.current?.(cloneSnapRenderState(stateRef.current));
+      const meta = recordValue(stateRef.current.__snapRender);
+      stateStore.update({
+        "/__snapRender/presentedEffects": meta?.presentedEffects ?? [],
+      });
     }
 
     setEffectRunKeys((current) => ({
@@ -184,49 +213,92 @@ export function SnapViewCoreInner({
           ? current.fireworks
           : 0,
     }));
-  }, [initialState, showConfetti, showFireworks, snapEffects]);
+  }, [initialState, showConfetti, showFireworks, snapEffects, stateStore]);
 
   const handlersRef = useRef(handlers);
   handlersRef.current = handlers;
 
+  const applyActionActivityState = useCallback(
+    (name: unknown, params: Record<string, unknown>, pending: boolean) => {
+      stateStore.update(
+        Object.fromEntries(
+          buildActionActivityStateChanges({
+            actionName: name,
+            params,
+            pending,
+          }).map(({ path, value }) => [path, value]),
+        ),
+      );
+    },
+    [stateStore],
+  );
+
+  const setActionPending = useCallback(
+    (name: unknown, params: Record<string, unknown>) => {
+      pendingActionCountRef.current += 1;
+      setHasPendingAction(true);
+      setActionActivityVersion((version) => version + 1);
+      applyActionActivityState(name, params, true);
+    },
+    [applyActionActivityState],
+  );
+
+  const setActionSettled = useCallback(
+    (name: unknown, params: Record<string, unknown>) => {
+      pendingActionCountRef.current = Math.max(
+        0,
+        pendingActionCountRef.current - 1,
+      );
+      applyActionActivityState(name, params, false);
+      if (pendingActionCountRef.current === 0) {
+        setHasPendingAction(false);
+      }
+      setActionActivityVersion((version) => version + 1);
+    },
+    [applyActionActivityState],
+  );
+
   const handleAction = useCallback((name: unknown, params: unknown) => {
     const inputs = (stateRef.current.inputs ?? {}) as Record<string, JsonValue>;
     const p = (params ?? {}) as Record<string, unknown>;
     const h = handlersRef.current;
+    let result: unknown;
+    setActionPending(name, p);
+
     switch (name) {
       case "submit":
-        h.submit(String(p.target ?? ""), inputs);
+        result = h.submit(String(p.target ?? ""), inputs);
         break;
       case "open_url":
-        h.open_url(String(p.target ?? ""));
+        result = h.open_url(String(p.target ?? ""));
         break;
       case "open_snap":
-        h.open_snap(String(p.target ?? ""));
+        result = h.open_snap(String(p.target ?? ""));
         break;
       case "open_mini_app":
-        h.open_mini_app(String(p.target ?? ""));
+        result = h.open_mini_app(String(p.target ?? ""));
         break;
       case "view_cast":
-        h.view_cast({ hash: String(p.hash ?? "") });
+        result = h.view_cast({ hash: String(p.hash ?? "") });
         break;
       case "view_profile":
-        h.view_profile({ fid: Number(p.fid ?? 0) });
+        result = h.view_profile({ fid: Number(p.fid ?? 0) });
         break;
       case "view_channel":
-        h.view_channel({ channelKey: String(p.channelKey ?? "") });
+        result = h.view_channel({ channelKey: String(p.channelKey ?? "") });
         break;
       case "compose_cast":
-        h.compose_cast({
+        result = h.compose_cast({
           text: p.text ? String(p.text) : undefined,
           channelKey: p.channelKey ? String(p.channelKey) : undefined,
           embeds: Array.isArray(p.embeds) ? (p.embeds as string[]) : undefined,
         });
         break;
       case "view_token":
-        h.view_token({ token: String(p.token ?? "") });
+        result = h.view_token({ token: String(p.token ?? "") });
         break;
       case "send_token":
-        h.send_token({
+        result = h.send_token({
           token: String(p.token ?? ""),
           amount: p.amount ? String(p.amount) : undefined,
           recipientFid: p.recipientFid ? Number(p.recipientFid) : undefined,
@@ -236,13 +308,13 @@ export function SnapViewCoreInner({
         });
         break;
       case "swap_token":
-        h.swap_token({
+        result = h.swap_token({
           sellToken: p.sellToken ? String(p.sellToken) : undefined,
           buyToken: p.buyToken ? String(p.buyToken) : undefined,
         });
         break;
       case "send_transaction":
-        h.send_transaction?.({
+        result = h.send_transaction?.({
           chainId: String(p.chainId ?? ""),
           to: String(p.to ?? ""),
           data: optionalString(p.data),
@@ -256,11 +328,30 @@ export function SnapViewCoreInner({
       default:
         break;
     }
-  }, []);
+
+    if (result instanceof Promise) {
+      void result.finally(() => {
+        setActionSettled(name, p);
+      }).catch(() => {});
+    } else {
+      setActionSettled(name, p);
+    }
+    return result;
+  }, [setActionPending, setActionSettled]);
+
+  const showLoadingOverlay =
+    loading ||
+    hasPendingAction ||
+    (actionActivityVersion >= 0 && pendingActionCountRef.current > 0);
 
   return (
-    <View style={styles.container}>
-      {loading ? (
+    <View
+      style={styles.container}
+      onStartShouldSetResponderCapture={() =>
+        hasPendingSnapAction(stateRef.current)
+      }
+    >
+      {showLoadingOverlay ? (
         loadingOverlay === undefined ? (
           <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
         ) : (
@@ -271,12 +362,8 @@ export function SnapViewCoreInner({
         <SnapCatalogView
           key={pageKey}
           spec={spec}
-          state={initialState}
+          store={stateStore}
           loading={false}
-          onStateChange={(changes) => {
-            applyStatePaths(stateRef.current, changes);
-            onRenderStateChange?.(cloneSnapRenderState(stateRef.current));
-          }}
           onAction={handleAction}
         />
       </SnapVersionProvider>

package/src/react-native/types.ts

@@ -1,5 +1,6 @@
 import type { Spec } from "@json-render/core";
 import type { SnapRenderState } from "../render-state";
+import type { SnapTransactionResult } from "../schemas";
 
 export type { SnapRenderState };
 
@@ -50,5 +51,7 @@ export type SnapActionHandlers = {
     recipientAddress?: string;
   }) => void;
   swap_token: (params: { sellToken?: string; buyToken?: string }) => void;
-  send_transaction?: (params: SnapSendTransactionParams) => void;
+  send_transaction?: (
+    params: SnapSendTransactionParams,
+  ) => void | Promise<void | SnapTransactionResult>;
 };

package/src/render-state.ts

@@ -7,6 +7,7 @@ export type SnapRenderStateChanges =
   | undefined;
 
 const SNAP_RENDER_STATE_META_KEY = "__snapRender";
+const ACTION_ACTIVITY_KEY_MAX_LENGTH = 64;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -121,6 +122,51 @@ export function applyStatePaths(
   }
 }
 
+function sanitizeActionActivityKey(value: string): string {
+  const sanitized = value
+    .trim()
+    .slice(0, ACTION_ACTIVITY_KEY_MAX_LENGTH)
+    .replace(/[^A-Za-z0-9_.-]/g, "_");
+  return sanitized || "action";
+}
+
+function getActionActivityKey(
+  actionName: unknown,
+  params: Record<string, unknown>,
+): string {
+  const explicitKey = params.activityKey;
+  return sanitizeActionActivityKey(
+    typeof explicitKey === "string" && explicitKey.trim()
+      ? explicitKey
+      : String(actionName || "action"),
+  );
+}
+
+export function buildActionActivityStateChanges({
+  actionName,
+  params,
+  pending,
+}: {
+  actionName: unknown;
+  params: Record<string, unknown>;
+  pending: boolean;
+}): { path: string; value: unknown }[] {
+  const key = getActionActivityKey(actionName, params);
+  return [
+    { path: `/actions/${key}/name`, value: String(actionName || "action") },
+    { path: `/actions/${key}/pending`, value: pending },
+  ];
+}
+
+export function hasPendingSnapAction(model: SnapRenderState): boolean {
+  const actions = model.actions;
+  if (!isRecord(actions)) return false;
+
+  return Object.values(actions).some(
+    (action) => isRecord(action) && action.pending === true,
+  );
+}
+
 export function getUnpresentedSnapEffects(
   model: SnapRenderState,
   effects: readonly string[] | undefined,

package/src/schemas.ts

@@ -107,10 +107,9 @@ const surfaceSchema = z.discriminatedUnion("type", [
 const fidSchema = z.number().int().nonnegative();
 const userSchema = z.object({ fid: fidSchema });
 
-export const payloadSchema = z
+const basePayloadSchema = z
   .object({
     fid: fidSchema.optional(), // deprecated in favor of user.fid
-    inputs: z.record(z.string(), postInputValueSchema).default({}),
     timestamp: z.number().int(),
     audience: z.string(),
     user: userSchema,
@@ -118,6 +117,58 @@ export const payloadSchema = z
   })
   .strip();
 
+const snapSendTransactionParamsSchema = z
+  .object({
+    chainId: z.string(),
+    to: z.string(),
+    data: z.string().optional(),
+    value: z.string().optional(),
+    gas: z.string().optional(),
+    gasPrice: z.string().optional(),
+    maxFeePerGas: z.string().optional(),
+    maxPriorityFeePerGas: z.string().optional(),
+  })
+  .strict();
+
+export type SnapSendTransactionParams = z.infer<
+  typeof snapSendTransactionParamsSchema
+>;
+
+const snapTransactionSuccessSchema = z
+  .object({
+    success: z.literal(true),
+    transactionHash: z.string(),
+  })
+  .strict();
+
+const snapTransactionFailureSchema = z
+  .object({
+    success: z.literal(false),
+    reason: z
+      .enum(["rejected_by_user", "failed", "unknown"])
+      .optional()
+      .default("unknown"),
+    message: z.string().optional(),
+    code: z.union([z.string(), z.number()]).optional(),
+    transactionHash: z.string().optional(),
+  })
+  .strict();
+
+export const snapTransactionResultSchema = z.discriminatedUnion("success", [
+  snapTransactionSuccessSchema,
+  snapTransactionFailureSchema,
+]);
+
+export type SnapTransactionResult = z.infer<
+  typeof snapTransactionResultSchema
+>;
+
+export const payloadSchema = basePayloadSchema
+  .extend({
+    inputs: z.record(z.string(), postInputValueSchema).default({}),
+  })
+  .strip();
+
 export type SnapPayload = z.infer<typeof payloadSchema>;
 
 /** JFS payload shape for POST minus deprecated `fid`; used for GET auth via payload header. */
@@ -127,6 +178,7 @@ export type SnapGetPayload = z.infer<typeof getPayloadSchema>;
 
 export const ACTION_TYPE_GET = "get" as const;
 export const ACTION_TYPE_POST = "post" as const;
+export const ACTION_TYPE_TRANSACTION_RESULT = "transaction_result" as const;
 
 const snapGetActionSchema = z.object({
   type: z.literal(ACTION_TYPE_GET),
@@ -144,9 +196,28 @@ const snapPostActionSchema = payloadSchema.extend({
 
 export type SnapPostAction = z.infer<typeof snapPostActionSchema>;
 
+export const transactionResultPayloadSchema = basePayloadSchema
+  .extend({
+    type: z.literal(ACTION_TYPE_TRANSACTION_RESULT),
+    transaction: z
+      .object({
+        request: snapSendTransactionParamsSchema,
+        result: snapTransactionResultSchema,
+      })
+      .strict(),
+  })
+  .strip();
+
+export type SnapTransactionResultPayload = z.infer<
+  typeof transactionResultPayloadSchema
+>;
+
+export type SnapTransactionResultAction = SnapTransactionResultPayload;
+
 export const snapActionSchema = z.discriminatedUnion("type", [
   snapGetActionSchema,
   snapPostActionSchema,
+  transactionResultPayloadSchema,
 ]);
 
 export type SnapAction = z.infer<typeof snapActionSchema>;

package/src/server/parseRequest.ts

@@ -1,12 +1,15 @@
 import { z } from "zod";
 import {
+  ACTION_TYPE_TRANSACTION_RESULT,
   ACTION_TYPE_GET,
   ACTION_TYPE_POST,
   getPayloadSchema,
   payloadSchema,
+  transactionResultPayloadSchema,
   type SnapAction,
   type SnapPayload,
   type SnapGetPayload,
+  type SnapTransactionResultPayload,
 } from "../schemas";
 import { decodePayload, parseJfs, verifyJFS } from "./verify";
 import { SNAP_PAYLOAD_HEADER } from "../constants";
@@ -121,9 +124,14 @@ async function parsePostRequest(
   request: Request,
   options: ParseRequestOptions,
 ): Promise<ParseRequestResult> {
-  const result = await validateJfsPayload({
+  const result = await validateJfsPayload<
+    SnapPayload | SnapTransactionResultPayload
+  >({
     jfsText: await request.text(),
-    schema: payloadSchema,
+    schema: (decodedPayload) =>
+      isTransactionResultPayload(decodedPayload)
+        ? transactionResultPayloadSchema
+        : payloadSchema,
     request,
     options,
   });
@@ -142,12 +150,30 @@ async function parsePostRequest(
     };
   }
 
+  if (isTransactionResultPayload(payload)) {
+    return {
+      success: true,
+      action: payload,
+    };
+  }
+
   return {
     success: true,
     action: { type: ACTION_TYPE_POST, ...payload },
   };
 }
 
+function isTransactionResultPayload(
+  payload: unknown,
+): payload is { type: typeof ACTION_TYPE_TRANSACTION_RESULT } {
+  return (
+    payload !== null &&
+    typeof payload === "object" &&
+    "type" in payload &&
+    payload.type === ACTION_TYPE_TRANSACTION_RESULT
+  );
+}
+
 /**
  * Shared pipeline for authenticated snap requests: parse the JFS envelope,
  * decode and schema-validate the payload, optionally verify the JFS signature
@@ -156,7 +182,9 @@ async function parsePostRequest(
  *
  * Both GET (payload header) and POST (request body) feed into this.
  */
-async function validateJfsPayload<T extends SnapPayload | SnapGetPayload>({
+async function validateJfsPayload<
+  T extends SnapPayload | SnapGetPayload | SnapTransactionResultPayload,
+>({
   jfsText,
   schema,
   request,
@@ -164,7 +192,7 @@ async function validateJfsPayload<T extends SnapPayload | SnapGetPayload>({
   invalidJsonMessage,
 }: {
   jfsText: string;
-  schema: z.ZodType<T>;
+  schema: z.ZodType | ((decodedPayload: unknown) => z.ZodType);
   request: Request;
   options: ParseRequestOptions;
   invalidJsonMessage?: string;
@@ -183,14 +211,17 @@ async function validateJfsPayload<T extends SnapPayload | SnapGetPayload>({
   }
   const jfs = parsed.jfs;
 
-  const payloadParsed = schema.safeParse(decodePayload(jfs.payload));
+  const decodedPayload = decodePayload(jfs.payload);
+  const selectedSchema =
+    typeof schema === "function" ? schema(decodedPayload) : schema;
+  const payloadParsed = selectedSchema.safeParse(decodedPayload);
   if (!payloadParsed.success) {
     return {
       ok: false,
       error: { type: "validation", issues: payloadParsed.error.issues },
     };
   }
-  const payload = payloadParsed.data;
+  const payload = payloadParsed.data as T;
 
   if (!options.skipJFSVerification) {
     const verified = await verifyJFS(jfs);

package/src/ui/button.ts

@@ -8,6 +8,7 @@ export const buttonProps = z.object({
   label: z.string().min(1).max(BUTTON_MAX_LABEL_CHARS),
   variant: z.enum(BUTTON_VARIANTS).optional(),
   icon: z.enum(ICON_NAMES).optional(),
+  disabled: z.boolean().optional(),
 });
 
 export type ButtonProps = z.infer<typeof buttonProps>;

package/src/ui/catalog.ts

@@ -23,6 +23,10 @@ const snapClientParams = z.object({
   client_action: z.record(z.string(), z.unknown()),
 });
 
+const activityParams = {
+  activityKey: z.string().min(1).max(64).optional(),
+};
+
 /**
  * json-render catalog for snap elements.
  *
@@ -121,32 +125,32 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     submit: {
       description:
         "POST to snap server with signed body (fid, inputs, timestamp, signature); response is next snap page.",
-      params: z.object({ target: z.string() }),
+      params: z.object({ target: z.string(), ...activityParams }),
     },
     open_url: {
       description: "Open external URL in browser.",
-      params: z.object({ target: z.string() }),
+      params: z.object({ target: z.string(), ...activityParams }),
     },
     open_snap: {
       description:
         "Open a snap URL inline. The client renders the target as a snap rather than opening a browser.",
-      params: z.object({ target: z.string() }),
+      params: z.object({ target: z.string(), ...activityParams }),
     },
     open_mini_app: {
       description: "Open target URL as a Farcaster mini app.",
-      params: z.object({ target: z.string() }),
+      params: z.object({ target: z.string(), ...activityParams }),
     },
     view_cast: {
       description: "Navigate to a cast by hash.",
-      params: z.object({ hash: z.string() }),
+      params: z.object({ hash: z.string(), ...activityParams }),
     },
     view_profile: {
       description: "Navigate to a user profile by FID.",
-      params: z.object({ fid: z.number() }),
+      params: z.object({ fid: z.number(), ...activityParams }),
     },
     view_channel: {
       description: "Navigate to a Farcaster channel by channel key.",
-      params: z.object({ channelKey: z.string() }),
+      params: z.object({ channelKey: z.string(), ...activityParams }),
     },
     compose_cast: {
       description: "Open the cast composer with optional pre-filled content.",
@@ -154,11 +158,12 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         text: z.string().optional(),
         channelKey: z.string().optional(),
         embeds: z.array(z.string()).optional(),
+        ...activityParams,
       }),
     },
     view_token: {
       description: "View a token in the wallet. Token is a CAIP-19 identifier.",
-      params: z.object({ token: z.string() }),
+      params: z.object({ token: z.string(), ...activityParams }),
     },
     send_token: {
       description: "Open send flow for a token. Token is CAIP-19.",
@@ -167,6 +172,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         amount: z.string().optional(),
         recipientFid: z.number().optional(),
         recipientAddress: z.string().optional(),
+        ...activityParams,
       }),
     },
     swap_token: {
@@ -174,6 +180,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
       params: z.object({
         sellToken: z.string().optional(),
         buyToken: z.string().optional(),
+        ...activityParams,
       }),
     },
     send_transaction: {
@@ -188,6 +195,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         gasPrice: z.string().optional(),
         maxFeePerGas: z.string().optional(),
         maxPriorityFeePerGas: z.string().optional(),
+        ...activityParams,
       }),
     },
     paginator_next: {