Action Chaining

The POST request part of the Action API now also supports Action chaining, which allows the confirmation of an action on-chain to present the context of a new action to the user, constructing what is essentially a 'chain' of actions in succession.

To enable Action chaining, make these changes to the specification in the POST request:

export interface ActionPostResponse<T extends ActionType = ActionType> {
  /** base64 encoded serialized transaction */
  transaction: string;
  /** describes the nature of the transaction */
  message?: string;
  links?: {
    /**
     * The next action in a successive chain of actions to be obtained after
     * the previous was successful.
     */
    next: NextActionLink;
  };
}

export type NextActionLink = PostNextActionLink | InlineNextActionLink;

/** @see {NextActionPostRequest} */
export interface PostNextActionLink {
  /** Indicates the type of the link. */
  type: "post";
  /** Relative or same origin URL to which the POST request should be made. */
  href: string;
}

/**
 * Represents an inline next action embedded within the current context.
 */
export interface InlineNextActionLink {
  /** Indicates the type of the link. */
  type: "inline";
  /** The next action to be performed */
  action: NextAction;
}

To make use of chaining, the links.next section of the ActionPostResponse must include one of these (both shown in the snippet):

• PostNextActionLink - This is a POST request link with the same origin callback url to receive the signature and user's account in the body. This callback url should respond with a NextAction.

• InlineNextActionLink - Inline metadata for the next action to be presented to the user immediately after the transaction has confirmed. No callback will be made.

After a transaction with an ActionPostResponse is signed by the user and confirmed on-chain, the Blink client should either:

• Execute the callback request to fetch and display the NextAction;

• Or, if a NextAction is already provided via links.next, the Blink client should update the displayed metadata and make no callback request.

If the callback URL doesn't have the same origin as the initial POST request, no callback request should be made. Blink clients should display an error notifying the user of the problem. Here's an example:

/** The next action to be performed */
export type NextAction = Action<"action"> | CompletedAction;

/** The completed action, used to declare the "completed" state within action chaining. */
export type CompletedAction = Omit<Action<"completed">, "links">;

Based on the type, the next action should be presented to the user through a Blink client in one of the following ways:

• action - (default) A standard action that will allow the user to see the included Action metadata, interact with the provided LinkedActions, and continue to chain any subsequent actions.

• completed - The terminal state of an action chain that can update the Blink interface with the included Action metadata, but will not allow the user to execute further actions.

If no links.next is provided, Blink clients should assume the current action is final action in the chain and present their "completed" message after the transaction is confirmed.