Manage bonds

Create, edit and trade bonds on the IXO Protocol, move them through their states, and make outcome payments and withdrawals. The code is illustrative.

The bonds module of the IXO Protocol ties funding to outcomes. A bond prices its token on a bonding curve, holds reserves, and receives outcome payments. This guide shows the messages that create and edit a bond, move it between states, buy, sell and swap, and make outcome payments and withdrawals, using the IXO MultiClient SDK (@ixo/impactxclient-sdk).

The module gives universal token bonding-curve functions to mint, burn, swap and settle bonds. A bond prices its tokens on a bonding curve (function_type and function_parameters), accepts one or more reserve_tokens, and passes through the states HATCH → OPEN → SETTLE (or FAILED). An alpha bond adds risk adjustment through MsgSetNextAlpha, which the bond's oracle_did controls.

Before you start

You need:

  • An IXO account with enough uixo for fees on the network you target. See Networks and endpoints.
  • An offline signer. See Creating signers in the SDK README.
  • For MsgCreateBond: a controller DID, a creator DID, an oracle DID if the bond is an alpha bond, and the reserve token denoms.
  • For MsgWithdrawReserve: the bond's allow_reserve_withdrawals flag must be true.
npm install @ixo/impactxclient-sdk
import { ixo, createSigningClient } from "@ixo/impactxclient-sdk";

const signingClient = await createSigningClient(RPC_ENDPOINT, offlineSigner);

Create a bond

const createBondMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgCreateBond",
  value: ixo.bonds.v1beta1.MsgCreateBond.fromPartial({
    bondDid: "did:ixo:bond:abc123",
    token: "BOND",
    name: "Solar Farm Alpha Bond",
    description: "Outcome-linked bond for verified solar production",
    functionType: "augmented_function",
    functionParameters: [
      ixo.bonds.v1beta1.FunctionParam.fromPartial({ param: "p0", value: "1" }),
    ],
    creatorDid: "did:ixo:creator123",
    controllerDid: "did:ixo:controller123",
    oracleDid: "did:ixo:oracle123",
    reserveTokens: ["uixo"],
    txFeePercentage: "0.5",
    exitFeePercentage: "1.0",
    feeAddress: feeAddress,
    reserveWithdrawalAddress: reserveAddress,
    maxSupply: { denom: "BOND", amount: "1000000" },
    orderQuantityLimits: [],
    sanityRate: "0",
    sanityMarginPercentage: "0",
    allowSells: true,
    allowReserveWithdrawals: false,
    alphaBond: true,
    batchBlocks: "1",
    outcomePayment: "0",
    creatorAddress: signerAddress,
  }),
};

await signingClient.signAndBroadcast(signerAddress, [createBondMsg], "auto");

Edit a bond, set alpha and change state

MsgEditBond changes a bond's name, description, order limits and sanity settings. MsgSetNextAlpha sets the next alpha value of an alpha bond, and only the bond's oracle can sign it. MsgUpdateBondState moves the bond to another state.

const editMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgEditBond",
  value: ixo.bonds.v1beta1.MsgEditBond.fromPartial({
    bondDid: "did:ixo:bond:abc123",
    name: "Solar Farm Alpha Bond v2",
    description: "Updated description",
    orderQuantityLimits: "",
    sanityRate: "",
    sanityMarginPercentage: "",
    editorDid: "did:ixo:editor123",
    editorAddress: signerAddress,
  }),
};

const setAlphaMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgSetNextAlpha",
  value: ixo.bonds.v1beta1.MsgSetNextAlpha.fromPartial({
    bondDid: "did:ixo:bond:abc123",
    alpha: "0.85",
    delta: "0.05",
    oracleDid: "did:ixo:oracle123",
    oracleAddress: oracleSignerAddress,
  }),
};

const updateStateMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgUpdateBondState",
  value: ixo.bonds.v1beta1.MsgUpdateBondState.fromPartial({
    bondDid: "did:ixo:bond:abc123",
    state: "OPEN",
    editorDid: "did:ixo:editor123",
    editorAddress: signerAddress,
  }),
};
StateMeaning
HATCHInitial fundraising
OPENActive trading
SETTLESettlement
FAILEDThe bond failed

Buy, sell and swap

const buyMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgBuy",
  value: ixo.bonds.v1beta1.MsgBuy.fromPartial({
    buyerDid: "did:ixo:buyer123",
    amount: { denom: "BOND", amount: "1000000" },
    maxPrices: [{ denom: "uixo", amount: "100" }],
    bondDid: "did:ixo:bond:abc123",
    buyerAddress: signerAddress,
  }),
};

const sellMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgSell",
  value: ixo.bonds.v1beta1.MsgSell.fromPartial({
    sellerDid: "did:ixo:seller123",
    amount: { denom: "BOND", amount: "1000000" },
    bondDid: "did:ixo:bond:abc123",
    sellerAddress: signerAddress,
  }),
};

const swapMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgSwap",
  value: ixo.bonds.v1beta1.MsgSwap.fromPartial({
    swapperDid: "did:ixo:swapper123",
    bondDid: "did:ixo:bond:abc123",
    from: { denom: "uixo", amount: "1000" },
    toToken: "uatom",
    swapperAddress: signerAddress,
  }),
};

Outcome payments and withdrawals

MsgMakeOutcomePayment makes an outcome payment to the bond. MsgWithdrawShare takes a holder's share out. MsgWithdrawReserve takes money out of the reserve, if the bond allows it.

const outcomePayMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgMakeOutcomePayment",
  value: ixo.bonds.v1beta1.MsgMakeOutcomePayment.fromPartial({
    senderDid: "did:ixo:funder123",
    amount: "1000000",
    bondDid: "did:ixo:bond:abc123",
    senderAddress: signerAddress,
  }),
};

const withdrawShareMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgWithdrawShare",
  value: ixo.bonds.v1beta1.MsgWithdrawShare.fromPartial({
    recipientDid: "did:ixo:holder123",
    bondDid: "did:ixo:bond:abc123",
    recipientAddress: signerAddress,
  }),
};

const withdrawReserveMsg = {
  typeUrl: "/ixo.bonds.v1beta1.MsgWithdrawReserve",
  value: ixo.bonds.v1beta1.MsgWithdrawReserve.fromPartial({
    withdrawerDid: "did:ixo:treasury123",
    amount: [{ denom: "uixo", amount: "500000" }],
    bondDid: "did:ixo:bond:abc123",
    withdrawerAddress: signerAddress,
  }),
};

Check the result

Query the bond's state through the Blocksync GraphQL API, or through the ixo.bonds.v1beta1 query endpoints on the gRPC gateway API.

When something goes wrong

What you seeWhat to do
invalid function type or parametersfunction_type must be one of the supported curve types: power_function, sigmoid_function, swapper_function or augmented_function. Each needs its own set of function_parameters. See the bonds proto.
state transition rejectedThe bond's lifecycle limits which state can follow which. HATCH → OPEN needs the hatch threshold to be met. OPEN → SETTLE is usually called once the outcome obligation is met or the bond expires.
reserve withdrawal not allowedMsgWithdrawReserve fails when allow_reserve_withdrawals was false on MsgCreateBond. The flag cannot be changed.
alpha update unauthorizedOnly the bond's oracle_address, which resolves from oracle_did, can broadcast MsgSetNextAlpha. Confirm that the signer matches.

Next steps