DOCS / BUILD / INTEGRATION ADAPTERS

Integration adapters

Reference terminal · In progressiOS app · In progress

Developer notes. The adapter layer exists in ChimpDAO's reference payment terminal (TypeScript, Stellar testnet). It is not in the iOS app yet, where Swap and Grow are hidden.

Goal

One adapter interface so a Stellar protocol can plug into card authorisation without changing the signing layer. The contracts need no adapter: a card wallet or a Main account authorises any contract call through the standard Stellar authorisation, so the same wallet works with Soroswap, DeFindex or Blend without new contract code.

Where it lives

PIECEFILEROLE

StrategyProtocol

FILEsrc/modules/earn/registry/protocols.ts

ROLEThe interface every protocol adapter implements, and the registry of adapters

AuthShape

FILEsrc/chain/auth-tree.ts

ROLEDeclares what a protocol's call makes the signer authorise

Soroswap adapter

FILEsrc/modules/earn/soroswap/

ROLESwap, add and remove liquidity

DeFindex adapter

FILEsrc/modules/earn/defindex/

ROLEVault deposit and withdrawal

Blend adapter

FILEsrc/modules/earn/blend/

ROLELending pool supply and withdrawal (submit)

SOURCE

The reference terminal is open source. chimpdao-terminal on Radicle ↗

The interface

TYPESCRIPT · SIMPLIFIED

type StrategyProtocol = {
  id: string;
  name: string;
  openActions: StrategyAction[];    // menu for a new position
  manageActions: StrategyAction[];  // menu for an existing position
  venues?: (network) => StrategyVenue[];          // pools, vaults
  discover: (network, account) => Promise<StrategyPosition[]>;  // read live from chain
  summarize: (position) => PositionView;
  quote?: (ctx) => Promise<ActionQuote | null>;  // display only
  execute: (ctx) => Promise<{ hash; explorerUrl }>;
  canMove?: boolean;  // move a position between a card's wallet and the Main account
  move?: (ctx) => Promise<{ hash; explorerUrl }>;
};

type AuthShape = {
  signer(call): string | null;      // which address must authorise this call
  pulls(call, from): Call[];        // token transfers the callee pulls from it
};

How an adapter plugs into the card signature

The adapter builds the protocol call (contract, function, arguments) for the account that holds the position: the Main account or a card's wallet.
Its AuthShape declares the signer and the token transfers the callee pulls from it. Together they form the authorisation tree the card signs.
From a card's wallet, the chip signs the declared tree before any simulation. From the Main account, the simulation returns the entries and the chip signs them.
The transaction is simulated in enforce mode, its fees are sponsored, and it is submitted.

A wrong declaration fails in simulation, before any transaction exists, and a signed tree can never authorise more than it declares. The terminal pins each shape against the network's own answer in auth-tree.test.ts. Field-level detail of each call: see the Signed-intent spec.

What each adapter declares

PROTOCOLCALLSWHAT THE SIGNER AUTHORISES UNDERNEATH

Soroswap

CALLSswap_exact_tokens_for_tokens · add_liquidity · remove_liquidity

WHAT THE SIGNER AUTHORISES UNDERNEATHSwap: transfer of the amount in to the pool pair. Add: both legs to the pair, at pinned amounts. Remove: the LP token to the pair.

DeFindex

CALLSdeposit · withdraw

WHAT THE SIGNER AUTHORISES UNDERNEATHDeposit: transfer of the amount to the vault. Withdraw: nothing.

Blend

CALLSsubmit

WHAT THE SIGNER AUTHORISES UNDERNEATHOne transfer per request that puts tokens into the pool (supply, collateral, repayment).

Guards in the reference terminal

Swap: the quote is requested again just before signing; if the pool already pays less than the minimum shown, nothing is signed ("Price moved").
Swap and vault withdrawal: 0.5% bound on the amount received. Swap deadline: 5 minutes, inside the 10-minute authorisation window.
DeFindex: the vault's declared asset is checked before money moves.
Moving a position between a card's wallet and the Main account is one atomic router batch where a router is deployed (testnet), and two separate transactions otherwise.

Adding a protocol

Implement StrategyProtocol: menus, discovery of positions, a human-readable summary, an optional quote, execute.
Declare its AuthShape: who signs each call and what the callee pulls from the signer.
Register it in STRATEGY_PROTOCOLS.

Not yet

ITEMSTATUS

Test vectors for the iOS app (the contracts and terminal tests already show these refusals)

STATUSPlanned

Developer guide beyond these notes

STATUSPlanned

Adapters in the iOS app

STATUSIn progress

Edit this page in the repositoryCHIMPDAO DOCS · TESTNET