# Biconomy DeFi API Design Docs

## API Interfaces
There will be primary two namespaces:
- `/instructions/*`: returns instructions for some specific tasks, such as ccswap, abi encoded tx, withdraw, etc.
- `/mee/*`: handles mee quote and execute

### Denote `RuntimeBalance` In the Params
we will denote runtimeBalance as an object

{
  type: 'runtimeErc20Balance',
  targetAddr: string,
  tokenAddr: string,
  constraints?: {
    greaterThanOrEqualTo?: number;
    lessThanOrEqualTo?: number;
    equalTo?: number;
  }
}

## 1) `/instructions` Namespace

### Build Instructions With ABI

Idea: args should be similar to `nexus.buildComposable`

POST /instructions/build
{
  abiFragment: 'function supply(address asset, ...)'
  args: [
     ...
  ],
  to?: string,
  chainId?: number,
  value?: bigint
}

=> return instructions built from the ABI and tx data
{
  instructions: [...],
  ...otherMetadata,
}

### Find Best Route and Build Instructions For CcSwap

Same as the current version, will be renamed to `/instructions/quoteCcSwap`

GET /ccswap/quote
{
  data: {
    srcToken: string,
    dstToken: string,
    ...
  }
}

=> return instructions for the ccswap
{
  instructions: [...],
  ...otherMetadata,
}

### Compose APIs To Return All Instructions

POST /instructions/compose
[{
  type: 'api',
  endpoint: `/ccswap/quote`,
  data: {
    srcToken: string,
    dstToken: string,
    ...
}, {
  type: 'api',
  api: `/instructions/build`,
  data: {
    abiFragment: 'function supply(address asset, ...)'
    args: [
       ...
    ]
  },
}, {
  type: 'withdraw',
  data: {
    chainId: number,
    tokenAddress: string,
    amount: number | RuntimeBalanceObj
  }
}]

=> return composed instructions as well as their extra returned info
{
  instructions: [...],
  returnedData: [
      {...}, // other data from first call
      {...}, // other data from second call
      ...
  ],
}

## 2) `/mee` Namespace
### Generate a Payload to Sign

Idea: params for this should be identical to `meeClient.getFusionQuote`

POST /mee/quote
{
  trigger: {...},
  instructions: [...],
  feeToken?: {
    address: string,
    chainId: number,
  },
  lowerBoundTimestamp?: number,
  upperBoundTimestamp?: number,
}

=> return signature payload
{
  signaturePayload: string,
  fee: {...},
  ...otherMetadata,
}

### Execute the Tx with Signed Payload

POST /mee/execute
{
  signature: string,
  superTransaction: {
    trigger: {...},
    instructions: [...],
    feeToken: {...},
    ...
  }
}

=> return execution result and supertxHash
{
  success: boolean,
  supertxHash: string | null,
  error: string | null,
}

## Example Flow With TS

const { instructions } = await axios.post('/instructions/compose', [
  {
    type: 'api',
    endpoint: `/ccswap/quote`,
    data: {
      srcToken: '0x123...',
      dstToken: '0x456...',
      ...
    },
  },
  {
    type: 'api',
    endpoint: `/instructions/build`,
    data: {
      abiFragment: 'function supply(address asset, uint256 amount)'
      args: [
        '0x123..',
        {
          type: 'runtimeErc20Balance',
          targetAddr: '0x222..',
          tokenAddr: '0x123..',
          constraints: {
            greaterThanOrEqualTo: 100000;
          }
        }
      ]
    },
  },
  {
    type: 'withdraw',
      data: {
        chainId: number,
        tokenAddress: string,
        amount: {
          type: 'runtimeErc20Balance',
          targetAddr: '0x222..',
          tokenAddr: '0x123..',
          constraints: {
            greaterThanOrEqualTo: 100000;
          }
        }
      }     
    }
  }
])

const superTransaction = {
  trigger: {...},
  instructions: instructions,
  feeToken: {
    address: '0x123...',
    chainId: 1,
  },
  lowerBoundTimestamp: Date.now(),
  upperBoundTimestamp: Date.now() + 60 * 1000,
};
    
const { signaturePayload, fee } = await axios.post(
  '/mee/quote',
  superTransaction,
)

ensureFeeIsOk(fee)

const signature = signer.signMessage(signaturePayload)

const { success, supertxHash, error } = await axios.post('/mee/execute', {
  signature,
  superTransaction,
})

if (success) {
  console.log('superTx sent with hash: ', supertxHash)
} else {
  console.error('tx failed', error)
}

## Questions
- Do we need to somehow compose `/compose` and `/generateQuote` with 1 api call? Something like `/composeAndQuote`
- Should we also return tx data (`{to: ..., data: ... }`) somewhere, so user can send the tx directly to contract (is it possible for supertx at all?)
- I think we don't need protocol specific endpoint for now? Since should be easy enough to use the general `/instructions/build` endpoint to build anything.
- how do we denote future `runtimeBalanceMath` stuff
- in the compose endpoint, maybe for

{
    type: 'api',
    endpoint: `/instructions/build`,
    data: {...}
}

it's cleaner to just do

{
    type: 'abi',
    data: {...}
}

we can still have the `/instructions/build` endpoint for consuming directly.

## Notes
For pre-action compose, it would be more tricky than post action, since `ccswap/quote` does not support runtime balance.

But IMO it's fine not to support runtime balance for ccswap input, as least for now. Since usually pre-action(such as withdrawal from lending protocol) has a predictable fixed output.