Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update hip-551.md #1090

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update hip-551.md #1090

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dde87fd
Update hip-551.md
ty-swirldslabs Dec 19, 2024
e1e55e4
Update hip-551.md to clarify conditional branching
mgarbs Jan 23, 2025
a417c2a
Merge branch 'main' into update-hip-551
mgarbs Jan 23, 2025
79e0cbb
Add throttle definition
ty-swirldslabs Jan 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 99 additions & 60 deletions HIP/hip-551.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,70 +2,74 @@
hip: 551
title: Batch transactions
author: Piotr Swierzy <[email protected]>
working-group: Nick Poorman <@nickpoorman>, Michael Garber <@mgarbs>, Ashe Oro <@Ashe-Oro>, Bug Bytes <@bugbytes>, Patrick Woo-Sam <@pwoosam>
working-group: Nick Poorman <@nickpoorman>, Michael Garber <@mgarbs>, Ashe Oro <@Ashe-Oro>, Bug Bytes <@bugbytes>, Patrick Woo-Sam <@pwoosam>, Michael Heinrichs <@netopyr>, Ty Smith <@ty-swirldslabs>
type: Standards Track
category: Service
needs-council-approval: Yes
status: Accepted
last-call-date-time: 2023-10-26T07:00:00Z
created: 2022-07-25
discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/discussions/531
updated: 2024-01-10
updated: 2024-12-19
---

## Abstract

This HIP defines a mechanism to execute batch transactions such that a series of transactions(HAPI calls) depending on each other can be rolled into one transaction that passes the ACID test (atomicity, consistency, isolation, and durability)
This HIP defines a mechanism to execute batch transactions such that a series of transactions (HAPI calls) depending on each other can be rolled into one transaction that passes the ACID test (atomicity, consistency, isolation, and durability).

## Motivation

The existing implementation of transactions in the Hedera network does not allow multiple different HAPI transactions to be called in one single network transaction that would have all the ACID properties.
This makes it impossible to create more complicated flows without using smart contracts (which do not support all the HAPI transactions at this point) and listening to the mirror node to check the status of the previous transaction.
This way we can also achieve an abstraction away from smart contracts.
The existing implementation of transactions in the Hedera network does not allow multiple different HAPI transactions to be called in one single network transaction that would have all the ACID properties. This makes it impossible to create more complicated flows without using smart contracts (which do not support all the HAPI transactions at this point) and listening to the mirror node to check the status of the previous transaction.

This approach will abstract away the need for smart contracts in certain cases, simplifying development and offering better user experiences by ensuring that all or none of the grouped transactions are applied. This feature will provide enhanced security for transactions that require an atomic execution flow.

## Rationale
Atomic transactions chain is from the protobuf point of view just a list of `SignedTransactions` that's, why we based our new protobuf message on it,
we only have to change the `bodyBytes` field to be `repeated`, that way we can store there multiple transaction bodies,
`SignatureMap sigMap` can stay unchanged because it's defined as `repeated SignaturePair sigPair`.

## User stories
Introducing a feature that allows grouped HAPI transactions to execute atomically within a single network transaction will use-cases for native services, thereby simplifying development workflows. It will ensure that grouped transactions are either fully applied or fully rolled back, enhancing both security and the user experience by streamlining development and preventing partial executions or inconsistencies in critical transaction flows. This will guarantee a malicious user cannot inject a new transaction in between the execution of the original transactions (cannot perform a sandwich attack).

## User Stories

### Use Case 1: Account-bound NFTs

As a Hedera Token Service user, I want to be able to unfreeze an account, send an NFT, and freeze the account again in one ACID transaction to create an account-bound NFT collection, without using the smart contract service. This could be used to issue nontransferable NFTs as digital references or achievements.

### Use Case 2: Account-bound FTs

I want to unfreeze an account, send fungible tokens (FT), and freeze it again in one ACID transaction to create account-bound FT collections, such as game points or reputation points.

### Use Case 3: Complex Token Flows

I want to batch multiple token operations, such as wiping, minting, and transferring tokens, into one ACID transaction to avoid handling partially successful transactions.

### Use Case 4: Cross-Service Batch

I want to wipe a token, mint a token, transfer a token, and submit a topic message in one ACID transaction to enable complex flows across different Hedera services without smart contracts.

1. As a Hedera token service user, I want to be able to unfreeze an account, send an NFT, and freeze it again in one ACID transaction, that way I can achieve an account-bound NFT(nontransferable NFT) collection, without using the hedera smart contract service.
We can use nontransferable NFTs e.g. as someone’s achievements, the creation of digital references, etc.
### Use Case 5: Gift Token with Mint

2. As a Hedera token service user, I want to be able to unfreeze an account, send an FT and freeze it again in one ACID transaction, that way I can achieve an account-bound FT(nontransferable FT) collection, without using the hedera smart contract service.
We can use nontransferable FT e.g. as game points, reputation points, etc.
I want to mint and transfer tokens in one ACID transaction when gifting tokens to a user, simplifying the process and avoiding the need for separate transactions.

3. As a Hedera token service user, I want to be able to wipe a token, mint a token, and transfer a token in one ACID transaction.
That way a backend developer could create complicated flows without the need to use smart contracts and the need to handle partially successful flows in the backend,
e.g. the wipe transaction was successful but the mint transaction was not.
### Use Case 6: Revoke KYC and Wipe Tokens

4. As a Hedera service user, I want to be able to create batch transaction, that use multiple Hedera services e. g.
I want to be able to wipe a token, mint a token, transfer a token, and submit a topic message in one ACID transaction.
That way a backend developer could create complicated flows without the need to use smart contracts and the need to handle partially successful flows in the backend,
e.g. the wipe transaction was successful but the mint transaction was not.
I want to batch KYC granting, token wiping, and KYC revoking into one ACID transaction to avoid situations where tokens are transferred from a revoked KYC account before I can wipe them.

5. As a Hedera token admin, I want to be able to gift Alice some tokens. I want to be able to mint and transfer the tokens in a single transaction.
### Use Case 7: Batch Key Approval Workflow

6. As a Hedera token owner, I want to be able to wipe tokens from an account that I revoked the KYC. I want to be able to grant KYC, wipe tokens and revoke KYC in a single transaction.
As a Hedera network user managing multiple transactions with sensitive permissions, I want to enforce that a specific trusted entity (batch key holder) approves an entire batch transaction before it is submitted. This allows for a streamlined, secure approval process for high-stakes transactions, ensuring only authorized batches are executed in scenarios such as account fund transfers, asset movements, or sensitive permission updates.

## Specification

### Transaction Integrity


1. Each inner transaction within a batch should be treated as a self-contained transaction, unaware of its batch context.
2. If an inner transaction fails, all preceding inner transactions that succeeded still have to pay, even if their effects are not committed.
1. Each inner transaction within a batch should be treated as a self-contained transaction.
2. If an inner transaction fails, preceding transactions that succeeded will still incur fees, even though their effects are not committed.
3. Inner transactions are individually signed regular transactions indicating that once a person signs an inner transaction, they have agreed to its outcome.


### Batch Signatures

Each transaction must be individually signed. Signatures on the batch itself are unique to the batch and don't represent the inner transactions within. This way:
- Batch transactions require unique signatures for the batch itself. Inner transactions cannot be rearranged post-signature.
- The primary audience for batch transactions are developers and dApps but rather for developers and dApps. When someone signs a transaction, they individually agree to the outcome, thus the individual transaction signers within the batch need not sign the batch itself. The ability for developers and dApps to execute atomic transactions across different services on Hedera enable more flexibility and certainty when executing complex use cases.

- It's impossible for inner transactions to be rearranged post-signature.
- Batch transactions are not designed to solve a problem for retail users but rather for developers and dApps. When someone signs a transaction, they individually agree to the outcome, thus the individual transaction signers within the batch need not sign the batch itself.

### Handling Inner Transactions

Inner transactions, by design:
Expand All @@ -74,54 +78,89 @@ Inner transactions, by design:
2. Each pays for itself (node + network + service fees).
3. Have their own payer.
4. Are deduplicated on an individual basis.
5. Are authorized solely by their keys; batch keys are not used.
6. If one of the inner transactions has a child transaction, the parent transaction is in the batch, and the batch isn't successful, then the child transaction should also be reverted.
5. Are authorized solely by their keys; batch keys are not used for authorization.
6. If one of the inner transactions has a child transaction, the parent transaction is in the batch, and the batch isn’t successful, then the child transaction should also be reverted.

The batch:

1. Has its own payer and signatures.
2. Considers inner transactions as part of its signed bytes.
3. Makes the batch payer cover node+network fees for handling the batch, excluding inner transaction fees.
4. Has deduplication based on its unique transaction ID.
5. The submitter does not need to be authorized to carry out all the inner batch transactions. As with every transaction in Hedera, where the submitter can be any account as long as the transaction is properly signed.
6. The standard max transaction size must be respected.
3. The standard max transaction size must be respected.
4. Makes the batch payer cover node+network fees for handling the batch, excluding inner transaction fees.
5. Has deduplication based on its unique transaction ID.
6. The submitter does not need to be authorized to carry out all the inner batch transactions. As with every transaction in Hedera, where the submitter can be any account as long as the transaction is properly signed.

### BatchKey Introduction

- To prevent malicious actors from tampering with a batch (e.g., removing, reordering, or adding transactions), a `batchKey` will be introduced in the `TransactionBody`.
- The `batchKey` signals the trusted signer who can finalize the batch. This key ensures that batch transactions can only be submitted as a whole and prevents individual transactions from being executed outside the batch context.

### New Protobuf Changes

A batchKey will be added to the TransactionBody. In addition, the TransactionBody will include a new AtomicBatchTransactionBody.

```protobuf
message TransactionBody {
// Existing properties omitted.

We could create a new protobuf message based on `SignedTransaction` message:
```
message BatchTransaction {
/**
* TransactionBodies serialized into bytes, which must be signed
* The <b>entire public key</b> of the trusted batch assembler.
*
* Only Ed25519 and ECDSA(secp256k1) keys and hence signatures are currently supported.
*/
repeated bytes bodyBytes = 1;
Key batchKey = 63;

/**
* The signatures on the body with the new format, to authorize the transactions
*/
SignatureMap sigMap = 2;
oneof data {
// Existing values omitted.

AtomicBatchTransactionBody atomicBatchTransactionBody = 64;
}
}

```

## Backwards Compatibility
The AtomicBatchTransactionBody will contain the transaction(s) that make up the batch.

## Security Implications
```protobuf
message AtomicBatchTransactionBody {
repeated Transaction transactions = 1;
}

```

As part of ensuring the integrity of batched transactions, certain security measures are emphasized:
The top-level `AtomicBatchTransactionBody` must be signed by the `batchKey` specified in the included transactions. There may only be one `batchKey` set for all the transactions in the batch. i.e. Inner transaction X cannot have a different `batchKey` than inner transaction Y.

1. Inner transactions within a batch cannot be reordered post-batch-signature.
2. All signatures on the batch pertain solely to the batch and not the inner transactions.
We must return what transaction failed in the batch when the batch fails.

## How to Teach This
```protobuf
message TransactionReceipt {
// Existing properties omitted.

repeated ResponseCodeEnum batchTransactionStatus = 16;
}
```

## Reference Implementation
### Security Enhancements

## Rejected Ideas
We rejected the idea to add the support of conditional branching to the batch transactions,
because we don't think it's useful compared to the increase of complications in implementing the HIP.
1. The batch transaction system prevents malicious actors from tampering with transactions by requiring them to be processed as a single unit.
2. A `batchKey` ensures only the trusted assembler (e.g., Alice) can create a valid batch. Nodes attempting to disassemble the batch or alter it will invalidate the transaction.

## Open Issues
### Batch Transaction Timeout

## References
All inner transactions must execute within the standard `transactionValidStart` and `transactionValidDuration` (typically 3 minutes) to ensure they remain valid during batch processing.

SimiHunjan marked this conversation as resolved.
Show resolved Hide resolved
## Copyright/license
## Backward Compatibility

This proposal is backward compatible with existing Hedera transaction models, as it introduces a new message type for batch transactions without changing current transaction structures.

## Security Implications

Security is reinforced by ensuring that inner transactions cannot be executed outside the batch and by preventing malicious nodes from modifying batch transactions. The use of a `batchKey` ensures that only the trusted entity can assemble and submit the batch.

## Rejected Ideas

Conditional branching within batch transactions was rejected as it would introduce unnecessary complexity without significant value for the proposed use cases.
SimiHunjan marked this conversation as resolved.
Show resolved Hide resolved

## Open Issues

This document is licensed under the Apache License, Version 2.0 -- see [LICENSE](../LICENSE) or (https://www.apache.org/licenses/LICENSE-2.0)
The need to return details of failed transactions when a batch fails remains an open issue, as partial failures within the batch might require specific information to be returned to the user for debugging and recovery.
Loading