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.
Illustrative example. The snippets on this page show how each message is built. They are not a tested project you can run as written. You supply the signer and every identifier. Build against a test network, never against mainnet.
Before you start
You need:
- An IXO account with enough
uixofor 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'sallow_reserve_withdrawalsflag must betrue.
npm install @ixo/impactxclient-sdkimport { 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,
}),
};| State | Meaning |
|---|---|
HATCH | Initial fundraising |
OPEN | Active trading |
SETTLE | Settlement |
FAILED | The 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 see | What to do |
|---|---|
| invalid function type or parameters | function_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 rejected | The 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 allowed | MsgWithdrawReserve fails when allow_reserve_withdrawals was false on MsgCreateBond. The flag cannot be changed. |
| alpha update unauthorized | Only the bond's oracle_address, which resolves from oracle_did, can broadcast MsgSetNextAlpha. Confirm that the signer matches. |