Lifecycle Status

OnchainKit is a design system that offers components for onchain applications and allows you to manage the state of APIs and onchain transactions seamlessly within those components.

To give you complete control over the state of your components and the data they fetch, OnchainKit introduces a Lifecycle Status.

What is the Lifecycle Status?

The lifecycle status is the drummer of your components, maintaining a consistent tempo and rhythm for your components and the data they fetch. 🥁

It influences how the components work together and how you, as the developer, can tap into the rhythm and customize the behavior of your components. 🎶

How to listen to the Lifecycle status

The Lifecycle Status is a TypeScript object that provides easy access to the statusName and statusData properties, allowing you to stay informed and responsive.

import type { LifecycleStatus } from '@coinbase/onchainkit/transaction';
 
const handleOnStatus = useCallback((status: LifecycleStatus) => {
  console.log('LifecycleStatus', status);
}, []);
 
<Transaction onStatus={handleOnStatus}>
  // omitted component code for brevity
</Transaction>

Lifecycle Status vibes 🎸

The Lifecycle Status includes 3 states common to all components:

init

The component is initialized and ready for use.

{
  statusName: 'init';
  statusData: null;
}

success

The component has successfully completed its main action, such as swap or transaction.

{
  statusName: 'success';
  statusData: {
    // the data returned from the API or onchain operation
  };
}

error

The component has encountered an issue while fetching API data, executing an onchain operation, or needs to display a visual message to the user.

{
  statusName: 'error';
  statusData: {
    code: string; // The error code representing the location of the error
    error: string; // The error message providing developer details
    message: string; // The error message providing user-facing details
  };
}

Each component brings its own unique experience, and we have explored both the swap and transaction processes.

Lifecycle Status with <Swap />

amountChange

Any of the Swap Input fields have been updated.

{
  statusName: 'amountChange';
  statusData: {
    amountFrom: string;
    amountTo: string;
    tokenFrom?: Token;
    tokenTo?: Token;
    isMissingRequiredField: boolean;
  };
}

transactionPending

The transaction has been submitted to the network but has not yet been confirmed to be included in a block. During this pending state, the transaction is waiting to be validated by the network's consensus mechanism.

{
  statusName: 'transactionPending';
  statusData: null;
}

transactionApproved

The transaction has been verified to be valid and it has been included in a block however the transaction is not yet finalized.

{
  statusName: 'transactionApproved';
  statusData: {
    transactionHash: Hex;
    transactionType: 'Batched' | 'ERC20' | 'Permit2' | 'Swap';
  };
}

success

The transaction has been added to the blockchain and the transaction is considered final.

{
  statusName: 'success';
  statusData: {
    transactionReceipt: TransactionReceipt;
  };
}

Lifecycle Status with <Transaction />

transactionIdle

The transaction component is waiting for the user to take action.

{
  statusName: 'transactionIdle';
  statusData: null;
}

transactionPending

The transaction has been submitted to the network but has not yet been confirmed to be included in a block. During this pending state, the transaction is waiting to be validated by the network's consensus mechanism.

{
  statusName: 'transactionPending';
  statusData: null;
}

success

The transaction has been added to the blockchain and the transaction is considered final.

{
  statusName: 'success';
  statusData: {
    transactionReceipts: TransactionReceipt[];
  };
}

How to contribute to the Lifecycle Status

The lifecycle status is new for OnchainKit, and we are continuously iterating to make it better.

As you use it, we welcome your input via GitHub issues.

Your feedback helps us create an enhanced experience for everyone.