ActionCode

The ActionCode class represents an action code in the Action Codes Protocol. It encapsulates all the data and logic for a single action code, including its status, metadata, transaction details, and utility methods for validation and display.

Type Definitions

ActionCodeStatus

type ActionCodeStatus = 'pending' | 'resolved' | 'finalized' | 'expired' | 'error';

Represents the status of an action code.

ActionCodeMetadata

interface ActionCodeMetadata {
  description?: string;
  params?: Record<string, any>;
}

Metadata for the action code, including an optional description and parameters.

ActionCodeTransaction

interface ActionCodeTransaction {
  transaction?: string; // Solana: base64 string
  txSignature?: string; // Solana signature
  txType?: string; // Transaction type for categorization
  message?: string; // For sign-only mode: the message to be signed
  signedMessage?: string; // For sign-only mode: the signed message or signature
  intentType?: 'transaction' | 'sign-only'; // Explicit intent type
}

Represents transaction or message data attached to an action code.

ActionCodeFields

interface ActionCodeFields {
  code: string;
  prefix: string;
  pubkey: string;
  timestamp: number;
  signature: string;
  chain: string; // e.g., 'solana'
  transaction?: ActionCodeTransaction;
  metadata?: ActionCodeMetadata;
  expiresAt: number;
  status: ActionCodeStatus;
}

All fields required to construct an ActionCode instance.

ActionCode Class

Constructor

new ActionCode(fields: ActionCodeFields)

Creates a new ActionCode instance from the provided fields.

Static Methods

fromPayload

static fromPayload(input: ActionCodeFields): ActionCode

Creates an ActionCode from a plain object. Throws if required fields are missing.

fromEncoded

static fromEncoded(encoded: string): ActionCode

Creates an ActionCode from a base64-encoded string.

Instance Properties & Methods

encoded

get encoded: string

Returns a base64-encoded string of the action code fields.

isValid

isValid(protocol: ActionCodesProtocol): boolean

Checks if the action code is valid for the given protocol (signature, code format, not expired).

updateStatus

updateStatus(status: ActionCodeStatus): void

Updates the status of the action code.

json

get json: ActionCodeFields

Returns the raw fields as a plain object.

remainingTime

get remainingTime: number

Milliseconds remaining until expiration (0 if expired).

expired

get expired: boolean

Returns true if the code is expired.

chain

get chain: string

Returns the chain identifier (e.g., ‘solana’).

status

get status: ActionCodeStatus

Returns the current status of the action code.

code

get code: string

Returns the 8-character action code string.

prefix

get prefix: string

Returns the normalized prefix for the code.

pubkey

get pubkey: string

Returns the user’s public key.

transaction

get transaction: ActionCodeTransaction | undefined

Returns the transaction data, if any.

metadata

get metadata: ActionCodeMetadata | undefined

Returns the metadata object, if any.

description

get description: string | undefined

Returns the human-readable description from metadata.

params

get params: Record<string, any> | undefined

Returns the parameters from metadata.

timestamp

get timestamp: number

Returns the timestamp when the code was generated.

signature

get signature: string

Returns the user’s signature string.

displayString

get displayString: string

Returns a formatted string for display (e.g., “PREFIX-XXXXXX (solana, pending)“).

remainingTimeString

get remainingTimeString: string

Returns a human-readable string for remaining time (e.g., “1m 30s remaining” or “Expired”).

codeHash

get codeHash: string

Returns the code hash (used as code ID in protocol meta).

intentType

get intentType: 'transaction' | 'sign-only'

Returns the intent type for the action code.

Example

import { ActionCode } from "@actioncodes/protocol";

const fields: ActionCodeFields = {
  code: "ABC12345",
  prefix: "DEFAULT",
  pubkey: "...",
  timestamp: Date.now(),
  signature: "...",
  chain: "solana",
  expiresAt: Date.now() + 60000,
  status: "pending",
};

const actionCode = new ActionCode(fields);
console.log(actionCode.displayString); // e.g., "ABC12345 (solana, pending)"

Overview

Reference

Relayer

Type Definitions

ActionCodeStatus

ActionCodeMetadata

ActionCodeTransaction

ActionCodeFields

ActionCode Class

Constructor

Static Methods

fromPayload

fromEncoded

Instance Properties & Methods

encoded

isValid

updateStatus

json

remainingTime

expired

chain

status

code

prefix

pubkey

transaction

metadata

description

params

timestamp

signature

displayString

remainingTimeString

codeHash

intentType

Example

​Type Definitions

​ActionCodeStatus

​ActionCodeMetadata

​ActionCodeTransaction

​ActionCodeFields

​ActionCode Class

​Constructor

​Static Methods

​fromPayload

​fromEncoded

​Instance Properties & Methods

​encoded

​isValid

​updateStatus

​json

​remainingTime

​expired

​chain

​status

​code

​prefix

​pubkey

​transaction

​metadata

​description

​params

​timestamp

​signature

​displayString

​remainingTimeString

​codeHash

​intentType

​Example

Type Definitions

ActionCodeStatus

ActionCodeMetadata

ActionCodeTransaction

ActionCodeFields

ActionCode Class

Constructor

Static Methods

fromPayload

fromEncoded

Instance Properties & Methods

encoded

isValid

updateStatus

json

remainingTime

expired

chain

status

code

prefix

pubkey

transaction

metadata

description

params

timestamp

signature

displayString

remainingTimeString

codeHash

intentType

Example