DOCSEARCHbyAlgolia
Submit Docs

Safe Core SDK

repository·main·Indexed 43 days ago

https://github.com/safe-global/safe-core-sdk

A suite of TypeScript libraries for interacting with Safe Smart Accounts and the Safe Transaction Service API. The SDK includes @safe-global/protocol-kit for on-chain interactions, @safe-global/api-kit for off-chain transaction management, and relay-kit for ERC-4337 account abstraction features such as sponsorship and ERC-20 paymasters.

Tokens
51.7K
Snippets
180
Records
230
Agent score
55%

What's inside Safe Core SDK

  1. Overview of Safe{Core} SDK packages

    main

    The Safe{Core} SDK is a monorepo of TypeScript developer tools designed to facilitate interactions with Safe Smart Accounts and the Safe Transaction Service API. It also provides support for ERC-4337 compatibility.

    Key packages include:

    • @safe-global/protocol-kit: Used for interacting with Safe Smart Accounts (creating accounts, updating configurations, and executing transactions).
    • @safe-global/api-kit: A TypeScript library for the Safe Transaction Service API. It allows proposing and sharing transactions, collecting signatures from signers, and retrieving Safe information.
    • @safe-global/relay-kit: Enables ERC-4337 compatibility with Safe, allowing users to pay transaction fees using native blockchain tokens or ERC-20 tokens, or to use sponsored transactions.
    • @safe-global/types-kit: Provides common types used across the Safe Core SDK packages.

  2. Overview of Relay Kit

    main

    The Relay Kit enables ERC-4337 (Account Abstraction) capabilities with Safe. It allows users to manage transaction fees in several ways:

    1. Pay from Safe balance: Use the blockchain's native token (e.g., ETH) directly from the Safe account balance.
    2. Pay with ERC-20 tokens: Use other ERC-20 tokens to cover transaction fees.
    3. Sponsorship: Have transactions sponsored by a third party.

  3. Overview of @safe-global/types-kit

    main
    The @safe-global/types-kit is a specialized package containing the shared TypeScript definitions and types used throughout the Safe Core SDK ecosystem. It serves as a single source of truth for data structures, ensuring that different kits (API, Protocol, Relay, etc.) remain compatible and type-safe.

  4. Overview of Safe API Kit capabilities

    main

    The Safe API Kit is a software development kit designed to facilitate interaction with the Safe Transaction Service API. It enables developers to:

    • Propose and share transactions with other Safe signers.
    • Send signatures to the service for collection.
    • Retrieve Safe information, including transaction history, pending transactions, and enabled Modules and Guards.

  5. Understand the Safe Core SDK package ecosystem

    main

    The Safe Core SDK is a monorepo of developer tools designed to interact with Safe Smart Accounts and the Safe Transaction Service API. It is composed of several specialized kits that handle different aspects of the Safe lifecycle:

    • @safe-global/protocol-kit: Handles on-chain interactions with Safe contracts. Use this to deploy new Safes, fetch contract state (nonce, threshold, owners, modules), build transaction objects, approve transactions on-chain, and execute transactions once confirmations are met.
    • @safe-global/api-kit: Handles off-chain interactions with the Safe Transaction Service API. Use this to fetch Safe information, store transactions for off-chain signature collection, manage signatures, retrieve transaction history (pending, incoming, multisig), and query balances or token lists.
    • @safe-global/types-kit: Provides shared TypeScript types used across all other packages in the monorepo to ensure type safety and consistency.

    To perform a full workflow—deploying a Safe, creating a transaction, collecting off-chain signatures, and executing the transaction—you will typically use a combination of these kits.

  6. Use `sdk-starter-kit` playground scripts

    main

    The sdk-starter-kit provides high-level scripts that automate the process of creating, signing, and executing transactions or messages. These scripts automatically handle Safe deployment if the account does not exist and use the Safe Transaction Service for multi-owner coordination.

    • Create and execute a transaction: Standard transaction flow. pnpm play send-transactions
    • Create and execute Safe Operations: Flow for Safe Operations. pnpm play send-safe-operation
    • Create and execute on-chain messages: Flow for on-chain messages (regular transactions). pnpm play send-on-chain-message
    • Create and execute off-chain messages: Flow for off-chain messages. pnpm play send-off-chain-message
    • Setup Safe account owners: Demonstrate setting up Safe accounts with different owner configurations. pnpm play owner-management
    pnpm play send-transactions
pnpm play send-safe-operation
pnpm play send-on-chain-message
pnpm play send-off-chain-message
pnpm play owner-management

  7. How to get support for safe-core-sdk

    main

    If you encounter issues or have questions while using the SDK, follow these steps to find assistance:

    1. Consult Documentation: Check the official project documentation for usage instructions, FAQs, and troubleshooting.
    2. Search Existing Answers: Before asking a new question, search both GitHub issues and Stack Exchange to see if your problem has already been addressed.
    3. Use Stack Exchange: For general support and technical questions, use Stack Exchange and ensure you include the safe-core tag.

    Note on GitHub Issues: Do not use GitHub issues for general support or questions. The issue tracker is reserved for bug reports, feature requests, and code-related discussions.

  8. Perform interface checks for transaction status

    main

    When building a UI for Safe transactions, use these logic patterns to manage button visibility and user state:

    • Check if an owner has already signed: Iterate through the confirmations array in the SafeMultisigTransactionResponse to see if the current signerAddress is present.
    • Check if a transaction is ready to execute: Compare the length of the confirmations array against the Safe's safeThreshold.
    // Check if a Safe transaction is already signed by an owner
const isTransactionSignedByAddress = (
  signerAddress: string,
  transaction: SafeMultisigTransactionResponse
) => {
  const confirmation = transaction.confirmations.find(
    (confirmation) => confirmation.owner === signerAddress
  )
  return !!confirmation
}

// Check if a Safe transaction is ready to be executed
const isTransactionExecutable = (
  safeThreshold: number,
  transaction: SafeMultisigTransactionResponse
) => {
  return transaction.confirmations.length >= safeThreshold
}

  9. Integrate the Safe{Core} SDK using Protocol Kit and API Kit

    main
    To build applications that interact with Safe Smart Accounts and the Transaction Service, you should follow the integration guide which demonstrates how to combine @safe-global/protocol-kit and @safe-global/api-kit.

  10. Create a transaction (Single or MultiSend)

    main

    Use protocolKit.createTransaction() to create a transaction object.

    • Single Transaction: Pass an array containing one MetaTransactionData object. It will not be wrapped in a MultiSend.
    • MultiSend: Pass an array containing multiple MetaTransactionData objects. These will be bundled into a single MultiSend transaction.

    Options

    You can pass SafeTransactionOptionalProps as a second argument to specify safeTxGas, baseGas, gasPrice, gasToken, refundReceiver, or nonce.

    Managing Nonces

    If you create multiple transactions without specifying a nonce, they will share the same nonce, which invalidates all but the first one. To prevent this, use apiKit.getNextNonce(safeAddress) to fetch a unique nonce for each transaction.

    import { SafeTransactionOptionalProps } from '@safe-global/protocol-kit'
import { MetaTransactionData } from '@safe-global/types-kit'

const transactions: MetaTransactionData[] = [
  { to, data, value, operation },
  { to, data, value, operation }
]

const options: SafeTransactionOptionalProps = {
  safeTxGas, // Optional
  baseGas, // Optional
  gasPrice, // Optional
  gasToken, // Optional
  refundReceiver, // Optional
  nonce // Optional
}

const safeTransaction = await protocolKit.createTransaction({ transactions, options })

// To get a unique nonce for multiple pending transactions:
const nonce = await apiKit.getNextNonce(safeAddress)

  12. Confirm a transaction using Protocol Kit and API Kit

    main

    To confirm a transaction, owners must perform two steps: generate a signature using the Protocol Kit and then submit that signature to the Safe Transaction Service using the API Kit.

    1. Use protocolKit.signHash(safeTxHash) to generate the signature data.
    2. Use apiKit.confirmTransaction(safeTxHash, signatureData) to add the signature to the service.
    // transaction: SafeMultisigTransactionResponse

const hash = transaction.safeTxHash
let signature = await protocolKit.signHash(hash)
await apiKit.confirmTransaction(hash, signature.data)