Transaction helpers are high-level functions built into the OCAP Client that abstract away the complexity of creating and signing common transactions. Instead of manually constructing transaction objects, you can use these convenient methods for workflows like creating assets, transferring tokens, staking, and performing atomic swaps. These helpers ensure that the transaction structure is correct and simplify the development process significantly.
For a deeper understanding of the underlying transaction lifecycle, see Core Concepts: Transaction Lifecycle.
Account Management
migrateAccount
Migrates the ownership of an account to a new key pair. This is useful for key rotation or account recovery.
Parameters
- from
WalletObject(required) — The wallet object of the account to migrate from. - to
WalletObject(required) — The wallet object of the account to migrate to.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send an AccountMigrateTx
const txHash = await client.migrateAccount({
from: oldWallet,
to: newWallet,
});
console.log('Migration transaction hash:', txHash);delegate
Authorizes another account (the delegatee) to send specific types of transactions on behalf of the delegator. This is a powerful feature for creating secure, sandboxed permissions.
Parameters
- from
WalletObject(required) — The delegator's wallet, who is granting the privilege. - to
WalletObject(required) — The delegatee's wallet, who is receiving the privilege. - privileges
array(required) — An array of privilege objects specifying the allowed actions.- typeUrl
string(required) — The type URL of the transaction being permitted (e.g., 'fg:t'). - limit
object— Optional limits on the delegation.- tokens
array— Limits on specific fungible tokens. - assets
array— Limits on specific assets (NFTs).
- tokens
- typeUrl
Returns
- result
Promise<[string, string]>— An array containing the transaction hash and the newly created delegate address.
Example
Send a DelegateTx
const [txHash, delegateAddress] = await client.delegate({
from: userWallet,
to: appWallet,
privileges: [
{
typeUrl: 'fg:t:transfer_v2',
},
],
});
console.log('Delegation tx hash:', txHash);
console.log('Delegate address:', delegateAddress);revokeDelegate
Revokes previously granted permissions from a delegatee.
Parameters
- from
WalletObject(required) — The delegator's wallet. - to
WalletObject(required) — The delegatee's wallet. - privileges
array(required) — An array of privilege objects specifying the permissions to revoke.- typeUrl
string(required) — The type URL of the transaction to revoke (e.g., 'fg:t').
- typeUrl
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send a RevokeDelegateTx
const txHash = await client.revokeDelegate({
from: userWallet,
to: appWallet,
privileges: ['fg:t:transfer_v2'],
});
console.log('Revocation tx hash:', txHash);Asset (NFT) Management
createAsset
Creates a new asset (Non-Fungible Token) on the blockchain.
Parameters
- moniker
string(required) — A short, human-readable name for the asset. - data
object(required) — A JSON object containing the asset's metadata. - wallet
WalletObject(required) — The wallet of the asset's initial owner. - parent
string— The address of a parent asset, establishing a hierarchical link. - ttl
number(default:0) — Time-to-live in seconds after the first consumption. - readonly
boolean(default:false) — If true, the asset cannot be updated after creation. - transferrable
boolean(default:true) — If true, the asset can be transferred to another account. - display
object— Object for asset display metadata. - endpoint
object— Object for asset endpoint metadata. - tags
string[]— An array of tags for categorization. - delegator
string— The address of the delegator, if the transaction is sent by a delegatee.
Returns
- result
Promise<[string, string]>— An array containing the transaction hash and the address of the newly created asset.
Example
Send a CreateAssetTx
const [txHash, assetAddress] = await client.createAsset({
moniker: 'My First NFT',
data: {
typeUrl: 'json',
value: { name: 'Digital Collectible', description: 'A unique item.' },
},
wallet: userWallet,
});
console.log('Create asset tx hash:', txHash);
console.log('New asset address:', assetAddress);updateAsset
Updates the moniker and data fields of an existing, non-readonly asset.
Parameters
- address
string(required) — The address of the asset to update. - moniker
string(required) — The new moniker for the asset. - data
object(required) — The new JSON data object for the asset. - wallet
WalletObject(required) — The wallet of the asset's current owner.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send an UpdateAssetTx
const txHash = await client.updateAsset({
address: 'z3g...',
moniker: 'Updated NFT Name',
data: {
typeUrl: 'json',
value: { name: 'Updated Collectible', description: 'Now with more features!' },
},
wallet: userWallet,
});
console.log('Update asset tx hash:', txHash);createAssetFactory
Creates an asset factory, which acts as a template for minting multiple new assets with a consistent structure.
Parameters
- factory
object(required) — An object containing the factory's configuration.- name
string(required) — Name of the factory. - description
string(required) — Description of the factory. - limit
number(default:0) — The maximum number of assets that can be minted (0 for unlimited). - trustedIssuers
string[]— A list of wallet addresses allowed to mint from this factory. - input
object(required) — Defines the inputs required for minting. - output
object(required) — Defines the structure of the minted asset, often using templates.
- name
- wallet
WalletObject(required) — The wallet to own the factory.
Returns
- result
Promise<[string, string]>— An array containing the transaction hash and the address of the newly created factory.
Example
Send a CreateFactoryTx
const factoryConfig = {
name: 'Ticket Factory',
description: 'Mints event tickets',
limit: 1000,
input: { ... },
output: { ... },
};
const [txHash, factoryAddress] = await client.createAssetFactory({
factory: factoryConfig,
wallet: eventCreatorWallet,
});
console.log('Create factory tx hash:', txHash);
console.log('New factory address:', factoryAddress);acquireAsset
Acquires (mints) a new asset from an existing asset factory. This is typically initiated by the end-user who will own the asset.
Parameters
- itx
AcquireAssetV2Tx(required) — The inner transaction object, often prepared using a helper likepreMintAsset. - wallet
WalletObject(required) — The wallet of the user acquiring the asset. - delegator
string— The address of the delegator, if applicable.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send an AcquireAssetV2Tx
// First, prepare the minting transaction (e.g., on the server)
const itx = await client.preMintAsset({
factory: factoryAddress,
owner: userWallet.address,
wallet: issuerWallet,
});
// Then, the user sends the transaction
const txHash = await client.acquireAsset({ itx, wallet: userWallet });
console.log('Acquire asset tx hash:', txHash);mintAsset
This is the issuer-side counterpart to acquireAsset. It allows a trusted issuer to mint an asset from a factory and assign it to a specified owner.
Parameters
- itx
MintAssetTx(required) — The inner transaction object, often prepared usingpreMintAsset. - wallet
WalletObject(required) — The wallet of the trusted issuer.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send a MintAssetTx
const itx = await client.preMintAsset({
factory: factoryAddress,
owner: userWallet.address,
wallet: issuerWallet,
});
const txHash = await client.mintAsset({ itx, wallet: issuerWallet });
console.log('Mint asset tx hash:', txHash);Token Management
createTokenFactory
Creates a new factory for minting and burning a specific fungible token, often based on a bonding curve pricing model.
Parameters
- feeRate
number(default:0) — The fee rate for minting and burning operations. - curve
object(required) — The bonding curve configuration for pricing. - token
object(required) — The configuration for the token to be created. This includes properties like name, symbol, decimal, and maxTotalSupply. - data
object— Optional metadata for the token factory. - wallet
WalletObject(required) — The wallet of the factory's owner.
Returns
- result
Promise<[string, string]>— An array containing the transaction hash and the address of the newly created token factory.
Example
Send a CreateTokenFactoryTx
const [txHash, factoryAddress] = await client.createTokenFactory({
feeRate: 100, // 1%
curve: { fixedPrice: '1' }, // 1 native token per new token
token: {
name: 'My Community Token',
symbol: 'MCT',
decimal: 18,
maxTotalSupply: '1000000',
},
wallet: creatorWallet,
});
console.log('Create token factory tx hash:', txHash);
console.log('New token factory address:', factoryAddress);updateTokenFactory
Updates the feeRate and data for an existing token factory.
Parameters
- address
string(required) — The address of the token factory to update. - feeRate
number— The new fee rate for minting and burning. - data
object— New metadata for the token factory. - wallet
WalletObject(required) — The wallet of the factory's owner.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send an UpdateTokenFactoryTx
const txHash = await client.updateTokenFactory({
address: 'z2f...',
feeRate: 50, // 0.5%
wallet: ownerWallet,
});
console.log('Update token factory tx hash:', txHash);mintToken
Mints new tokens from a token factory in exchange for the reserve token (usually the native chain token). The cost is determined by the factory's bonding curve.
Parameters
- tokenFactory
string(required) — The address of the token factory. - amount
number(required) — The amount of new tokens to mint. - receiver
string(required) — The address that will receive the newly minted tokens. - maxReserve
number(required) — The maximum amount of reserve tokens the user is willing to pay. This acts as slippage protection. - data
object— Optional metadata for the transaction. - wallet
WalletObject(required) — The wallet initiating the mint.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send a MintTokenTx
const txHash = await client.mintToken({
tokenFactory: 'z2f...',
amount: 100,
receiver: userWallet.address,
maxReserve: 105, // Willing to pay up to 105 native tokens
wallet: userWallet,
});
console.log('Mint token tx hash:', txHash);burnToken
Burns existing tokens at a factory to receive the underlying reserve token in return. The amount of reserve token received is determined by the factory's bonding curve.
Parameters
- tokenFactory
string(required) — The address of the token factory. - amount
number(required) — The amount of tokens to burn. - receiver
string(required) — The address that will receive the reserve tokens. - minReserve
number(required) — The minimum amount of reserve tokens the user expects to receive. This acts as slippage protection. - data
object— Optional metadata for the transaction. - wallet
WalletObject(required) — The wallet initiating the burn.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send a BurnTokenTx
const txHash = await client.burnToken({
tokenFactory: 'z2f...',
amount: 50,
receiver: userWallet.address,
minReserve: 48, // Expecting to receive at least 48 native tokens
wallet: userWallet,
});
console.log('Burn token tx hash:', txHash);Transfer & Exchange
transfer
Transfers native tokens, custom fungible tokens, and/or assets (NFTs) to another account in a single transaction.
Parameters
- to
string(required) — The address of the recipient. - wallet
WalletObject(required) — The sender's wallet. - token
number(default:0) — The amount of the chain's native token to transfer. - assets
string[]— An array of asset addresses (NFTs) to transfer. - tokens
object[]— An array of custom fungible token objects to transfer.- address
string(required) — The address of the custom token contract. - value
number(required) — The amount of the custom token to transfer.
- address
- memo
string— An optional note for the transaction. - delegator
string— The delegator's address, if applicable.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send a TransferV2Tx
const txHash = await client.transfer({
to: 'z1sb...',
token: 1.5, // 1.5 of the native chain token
assets: ['z3g...'], // An NFT
tokens: [{ address: 'z2t...', value: 100 }], // 100 of a custom token
memo: 'Payment for services',
wallet: senderWallet,
});
console.log('Transfer tx hash:', txHash);prepareExchange
Prepares the sender's half of an atomic swap (exchange) transaction. It signs the sender's offer and returns a transaction object that can be passed to the receiver.
Parameters
- receiver
string(required) — The address of the other party in the exchange. - wallet
WalletObject(required) — The wallet of the user making the offer. - offerToken
number— Amount of native token offered. - offerAssets
string[]— Array of asset addresses offered. - offerTokens
object[]— Array of custom fungible tokens offered. - demandToken
number— Amount of native token demanded in return. - demandAssets
string[]— Array of asset addresses demanded in return. - demandTokens
object[]— Array of custom fungible tokens demanded. - memo
string— An optional note for the transaction.
Returns
- transactionObject
Promise<object>— The partially signed transaction object.
finalizeExchange
Finalizes the receiver's half of an atomic swap. It takes the partially signed transaction from prepareExchange, adds the receiver's signature, and returns the fully signed transaction object.
Parameters
- tx
object(required) — The transaction object returned fromprepareExchange. - wallet
WalletObject(required) — The wallet of the user accepting the offer. - data
object— Extra data in the multi-signature.
Returns
- transactionObject
Promise<object>— The fully signed, multi-signature transaction object.
exchange
Sends the fully signed exchange transaction to the blockchain. This can be called by either party after finalizeExchange is complete.
Parameters
- tx
object(required) — The transaction object returned fromfinalizeExchange. - wallet
WalletObject(required) — The wallet of the user submitting the transaction.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example (Full Exchange Flow)
Perform an atomic swap
// 1. Offerer prepares the transaction
const offerTx = await client.prepareExchange({
receiver: receiverWallet.address,
offerAssets: ['z3g...'], // Offer an NFT
demandToken: 10, // Demand 10 native tokens
wallet: offererWallet,
});
// 2. Receiver finalizes the transaction
const finalTx = await client.finalizeExchange({
tx: offerTx,
wallet: receiverWallet,
});
// 3. Either party can send the finalized transaction
const txHash = await client.exchange({ tx: finalTx, wallet: offererWallet });
console.log('Exchange tx hash:', txHash);Staking
stake
Stakes tokens and/or assets to a receiver address. Staking locks up resources, often in exchange for rewards or to provide security.
Parameters
- to
string(required) — The address of the stake receiver. - wallet
WalletObject(required) — The wallet of the staker. - assets
string[]— An array of asset addresses to stake. - tokens
object[]— An array of fungible token objects to stake. - locked
boolean(default:false) — Whether the stake is locked upon creation. - slashers
string[]— A list of addresses that are permitted to slash this stake. - message
string— An optional note for the stake.
Returns
- result
Promise<[string, string]>— An array containing the transaction hash and the address of the newly created stake.
Example
Send a StakeTx
const [txHash, stakeAddress] = await client.stake({
to: 'z1v...',
tokens: [{ address: 'z2t...', value: 5000 }],
message: 'Staking for validator rewards',
wallet: userWallet,
});
console.log('Stake tx hash:', txHash);
console.log('New stake address:', stakeAddress);revokeStake
Revokes previously staked tokens and/or assets, initiating the process to return them to the owner. Note that there may be an unbonding period before the assets can be claimed.
Parameters
- from
string(required) — The address of the stake to revoke from. - wallet
WalletObject(required) — The wallet of the stake owner. - assets
string[]— An array of asset addresses to revoke. - tokens
object[]— An array of fungible token objects to revoke.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send a RevokeStakeTx
const txHash = await client.revokeStake({
from: 'z6s...',
tokens: [{ address: 'z2t...', value: 1000 }],
wallet: userWallet,
});
console.log('Revoke stake tx hash:', txHash);claimStake
Claims items from a stake that have been successfully revoked and have passed their unbonding period.
Parameters
- from
string(required) — The address of the stake to claim from. - evidence
string(required) — The transaction hash of therevokeStaketransaction. - wallet
WalletObject(required) — The wallet of the stake owner.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send a ClaimStakeTx
const revokeTxHash = '0x123...abc';
const txHash = await client.claimStake({
from: 'z6s...',
evidence: revokeTxHash,
wallet: userWallet,
});
console.log('Claim stake tx hash:', txHash);slashStake
Allows a designated slasher to penalize a stake, typically for misbehavior. The slashed assets are transferred to a designated vault address.
Parameters
- from
string(required) — The address of the stake to slash. - reason
string(required) — A message explaining the reason for slashing. - wallet
WalletObject(required) — The wallet of the designated slasher. - assets
string[]— An array of asset addresses to slash. - tokens
object[]— An array of fungible token objects to slash.
Returns
- transactionHash
Promise<string>— The hash of the submitted transaction.
Example
Send a SlashStakeTx
const txHash = await client.slashStake({
from: 'z6s...',
reason: 'Validator downtime',
tokens: [{ address: 'z2t...', value: 500 }],
wallet: slasherWallet,
});
console.log('Slash stake tx hash:', txHash);