Aggregate Transaction

Aggregate transactions merge multiple transactions into one, allowing trustless swaps, and other advanced logic. Catapult does this by generating a one-time disposable smart contract.

../_images/aggregate-escrow-1.png

Example of an AggregateTransaction between two participants

When all involved accounts have cosigned the AggregateTransaction, all the inner transactions are executed at the same time.

Aggregate complete

An AggregateTransaction is complete when all the required participants have signed it.

The cosigners can sign the transaction without using the blockchain. Once it has all the required signatures, one of them can announce it to the network. If the inner transaction setup is valid, and there is no validation error, the transactions will get executed at the same time.

Aggregate complete transactions enable adding more transactions per block by gathering multiple inner transactions.

Aggregate bonded

An AggregateTransaction is bonded when it requires signatures from other participants.

Note

Before announcing an AggregateBondedTransaction, an account must announce and get confirmed a HashLockTransaction locking 10 cat.currency.

Once an aggregate bonded is announced, it reaches partial state and notifies its status through WebSockets or HTTP API calls.

Every time a cosignatory signs the transaction and announces an aggregate bonded cosignature, the network checks if all the required cosigners have signed. When all signatures are acquired, the transaction changes to unconfirmed state until the network includes it in a block.

../_images/aggregate-bonded-transaction-cycle.png

AggregateBondedTransaction cycle

Examples

Sending multiple transactions together

Dan announces an AggregateTransaction that merges two transfer transactions.

As Dan is the only required signatory, the transaction is considered complete after he signed. After announcing it to the network, Alice and Bob will receive the mosaics at the same time.

../_images/aggregate-sending-payouts.png

Sending payouts with aggregate complete transactions

Multi-asset escrowed transactions

In this example, Alice is buying tickets with currency.euro mosaic. When the ticket distributor cosigns the AggregateTransaction, the swap will happen atomically.

../_images/aggregate-escrow-1.png

Multi-Asset Escrowed Transactions

Paying for others fees

Alice sends 10 currency.euro to Bob using an app to make payments. But Alice doesn’t own cat.currency to pay the transaction fee.

By creating an AggregateBondedTransaction, Alice can convert EUR to cat.currency to pay the fee. Now, Alice and Bob can use Catapult’s public blockchain without ever having to buy or hold cat.currency units.

Since the app creator can put their own branding on the open source payment app, Alice and Bob may not even know they are using blockchain.

../_images/aggregate-paying-for-others-fees.png

Paying for others fees

Guides

Transaction schemas

AggregateTransaction

Announce an AggregateTransaction to combine multiple transactions together.

Version: 0x01

EntityType: 0x4141 (complete), 0x4241 (bonded)

Inlines:

Transaction

Property Type Description
transactionsHash Hash256 Aggregate hash of the aggregate transaction.
payloadSize uint32 Transaction payload size in bytes. In other words, the total number of bytes occupied by all inner transactions.
aggregateTransactionHeader_Reserved1 uint32 Reserved padding to align end of AggregateTransactionHeader on 8-byte boundary.
transactions array(Transaction, size=payloadSize) Array of inner transactions. An AggregateTransaction can contain up to 1000 inner transactions involving up to 15 different cosignatories. Other aggregate transactions are not allowed as inner transactions.
cosignatures array(Cosignature, __FILL__) Array of transaction cosignatures. Fills the remaining body space after transactions.

DetachedCosignature

Cosignature transactions are used to sign announced AggregateBondedTransactions with missing cosignatures.

Inlines:

Property Type Description
parentHash Hash256 AggregateBondedTransaction hash to cosign.

Cosignature

Property Type Description
signerPublicKey Key Cosigner public key.
signature Signature Transaction signature.

HashLockTransaction

Alias: LockFundsTransaction

Lock funds with a HashLockTransaction before sending an AggregateBondedTransaction. This transaction prevents spamming the partial cache with transactions that never will complete.

After enough funds are locked (10 cat.currency by default), the AggregateTransaction can be announced and added into the partial transactions cache.

Note

It’s not necessary to sign the aggregate and its HashLockTransaction with the same account. For example, if Bob wants to announce an aggregate and does not have enough funds to announce a HashLockTransaction, he can ask Alice to send the hash lock funds transaction for him sharing the signed AggregateTransaction hash.

Upon completion of the aggregate, the locked funds become available in the account that signed the initial HashLockTransaction. If the AggregateBondedTransaction duration is reached without being signed by all cosignatories, the locked amount becomes a reward collected by the block harvester at the height where the lock expires.

Version: 0x01

EntityType: 0x4148

Inlines:

Property Type Description
mosaic UnresolvedMosaic Locked mosaic (10 cat.currency).
duration BlockDuration Number of blocks for which a lock should be valid. Duration is allowed to lie up to 2 days.
hash Hash256 AggregateBondedTransaction hash that has to be confirmed before unlocking the mosaics.

Continue: Account Restrictions.