Skip to Content
PlatformOffchain and Onchain Flows

Offchain and Onchain Protocol Flows

Beav3r protocol currently has two main flow families:

  • offchain approval flow
  • onchain authorization flow

Use the offchain flow when the SDK caller executes the final action itself.

Use the onchain flow when the final action must be executed by an onchain executor contract with a signed authorization artifact.

  • offchain client + approval routing: @beav3r/sdk
  • shared protocol types/schemas: @beav3r/protocol
  • onchain helper utilities (artifact/executor helpers): @beav3r/protocol-onchain

Offchain flow (standard)

This is the default integration path:

  1. submit action with guard or guardAndWait
  2. Beav3r evaluates policy
  3. action is allowed, denied, or routed to signer approval
  4. caller handles the terminal result

Minimal offchain example:

import { Beav3r } from '@beav3r/sdk'
 
const client = new Beav3r({
  baseUrl: 'https://staging.server.beav3r.ai',
  apiKey: process.env.BEAV3R_API_KEY
})
 
const result = await client.guardAndWait(
  {
    actionType: 'payments.send_usdt',
    payload: { amount: 25, recipient: '0x1111111111111111111111111111111111111111' }
  },
  { pollIntervalMs: 2000, timeoutMs: 5 * 60 * 1000 }
)

Onchain flow (authorization + executor)

Trusted executor model (core concept)

Provisioning an onchain actor returns:

  • account: the supplied actor identity, returned in the actor record
  • executor: the contract address to trust onchain

Target contracts grant permissions to the executor address. At execution time, the target contract sees msg.sender = executor.

The executor only runs calls with a valid Beav3r authorization artifact. Beav3r authorization controls which calls can execute through the trusted executor.

This path adds an authorization artifact step:

  1. submit action with guardAndWait
  2. after approval, call authorizeOnchainAction
  3. normalize artifact (actionHash, keyId, signature)
  4. call executor contract executeWithAuth(...) onchain

Minimal onchain package usage:

npm install @beav3r/sdk@beta @beav3r/protocol-onchain viem

Typical structure:

  1. calls guardAndWait
  2. calls authorizeOnchainAction
  3. normalizes actionHash / keyId / signature
  4. sends executor executeWithAuth(...) onchain

Execution breakdown:

  1. executor receives target call + signed authorization payload
  2. executor verifies chain, executor address, account binding, expiry, and nonce replay
  3. executor asks verifier to validate signature trust against Beav3r signer registry
  4. if valid, executor performs to.call(...) to target contract
  5. target contract sees msg.sender = executor and applies permissions accordingly

Direct SDK-level onchain example:

import { Beav3r } from '@beav3r/sdk'
 
const client = new Beav3r({
  baseUrl: process.env.BEAV3R_BASE_URL,
  apiKey: process.env.BEAV3R_API_KEY
})
 
const transferData = '0x...' // encoded ERC20 transfer calldata
 
await client.guardAndWait({
  actionType: 'payments.send_usdt',
  payload: { amount: '70', calldata: transferData, chainId: 84532 }
})
 
const auth = await client.authorizeOnchainAction({
  projectId: process.env.BEAV3R_PROJECT_ID,
  account: '0xActorAccount',
  to: '0xTokenAddress',
  value: '0',
  data: transferData,
  chainId: 84532,
  nonce: Math.floor(Date.now() / 1000),
  expiresAt: Math.floor(Date.now() / 1000) + 1200,
  executor: '0xExecutorAddress'
})
 
// Use auth.item.artifact.payload + auth.item.artifact.signature
// to call executor.executeWithAuth(...) onchain.

Choosing the path

  • choose offchain when no onchain executor authorization is needed
  • choose onchain when execution must be bound to a signed artifact and executor contract
Last updated on
Projects and API KeysPolicy Scope Basics