# Breaking Change Without Deprecation: `signTransaction` Return Type Changed

[tomachianura]

Description

Breaking Change Without Deprecation: signTransaction Return Type Changed

Summary

The recent update to @hashgraph/sdk changed the return type of the signTransaction method from Uint8Array to SignatureMap without following proper deprecation protocols. This breaking change has significant negative impacts on applications using this method and requires substantial refactoring efforts.

Issue Description

In a recent version of @hashgraph/sdk, the following method signature was changed:

Before:

signTransaction(transaction: Transaction): Uint8Array;

After:

signTransaction(transaction: Transaction): SignatureMap;

This change was implemented on the same method name without any deprecation notice, migration path, or backward compatibility support. Modern software development practices recommend maintaining backward compatibility through proper deprecation cycles, especially for public-facing APIs.

Impact

This change has caused significant problems for our development team:

1. Unexpected runtime errors occurred immediately after upgrading the SDK
2. Our codebase required extensive refactoring to accommodate the new return type
3. Development time was diverted from feature work to fixing integration issues
4. Testing efforts had to be redirected to ensure the refactored code works correctly
5. This compromised our release schedule and increased development costs

Suggested Solution

To maintain backward compatibility while introducing new functionality:

1. Follow Proper Deprecation Protocol:

   • Mark the current method as deprecated with @deprecated annotations
   • Document the deprecation in release notes and README
   • Keep the original method functioning alongside the new one for at least one major version cycle

2. Add New Method Instead of Changing Existing Method:

   // Keep original method
   signTransaction(transaction: Transaction): Uint8Array;
   
   // Add new method with clear naming
   signTransactionWithSignatureMap(transaction: Transaction): SignatureMap;

3. Define a Deprecation Timeline:

   • Clearly communicate when the deprecated method will be removed
   • Provide migration guides for moving to the new method
   • Consider implementing console warnings when deprecated methods are used

Best Practices for SDK Evolution

For future reference, we recommend following these practices:

1. Semantic Versioning: Follow SemVer strictly for all releases
2. Change Log: Clearly document breaking changes in CHANGELOG.md
3. Migration Guides: Provide step-by-step guidance for upgrading
4. Deprecation Notices: Use proper annotations and runtime warnings
5. Breaking Changes: Reserve breaking changes for major version updates

Conclusion

Breaking changes without proper deprecation cycles create significant overhead for developers using the SDK. By implementing a proper deprecation strategy, SDK maintainers can provide new functionality while respecting the investment users have made in existing implementations.

We respectfully request that the team considers reverting this change or providing backward compatibility until proper deprecation can be implemented in a future major version release.

Steps to reproduce

1. install v0.44.0 or older
2. create an engine/script to sign any transaction using the signTransaction method.
3. update to version 0.51.0 or higher
4. verify the back compatibility is broken, and you'll be forced to adapt your code.

Additional context

No response

Hedera network

No response

Version

v0.59.0

Operating system

None

[0xivanov]

Thanks for raising this. You are absolutely correct that this was a breaking change.
We had a high priority client at the time that needed this and technically your suggestions for best practices were not viable.

Aside from that - the question here is did you manage to migrate fully to the new implementation?
If yes - please tell me in more detail how you used to use this func and how you are using it now, how much files did you have to change?
If no - we will try to document better the migration process.

[tomachianura]

Sorry, you're telling me that you've totally bypassed the best practices when updating the SDK of a public ledger just because a private and high priority client asked you to do so?

not sure how to take this.... if that's a joke, then LOL.
if that's not a joke, than....damn.

seriously, how can you bypass best practices just cause of a single customer, ignoring everybody else building on what's (at least supposed to be) a public ledger??

i'm speechless at that point.

To answer your question, i'll attach 2 images.... we have more than 6M lines, only counting *.ts files between smart-nodes v1 and smart-nodes v2. It took us a month to port v1 over the new sdk, and we're still working on the v2.

your favoritism towards a very special high priority customer has been costing us (one of the major project on hedera) several months of delay, and a massive amount of extra money spent.

[tomachianura]

can we kindly know who this high priority client is?
i guess we all deserve to know, considering Hedera is still supposed to be a public ledger, so we (community projects and builders) can get ready for new favouritism in the future.

[tomachianura]

Also, just out of curiosity, how can we become a high priority client as well?
do we need to pay, and if so, how much?

or most probably, do we need to be part of your alliances, or to know someone who knows someone, so we can be considered as well?

and if so, what about all the other builders who are not high priority client?
you just don't care about those projects, which are yet moving MILLIONS in TVL like we do?

[Permabull313]

Thanks for raising this. You are absolutely correct that this was a breaking change. We had a high priority client at the time that needed this and technically your suggestions for best practices were not viable.

Aside from that - the question here is did you manage to migrate fully to the new implementation? If yes - please tell me in more detail how you used to use this func and how you are using it now, how much files did you have to change? If no - we will try to document better the migration process.

Community member -> I cannot believe this is something Hedera is doing. How is a public ledger, a technology that supposedly will have the whole world running on it literally introducing a breaking change which has affected so many projects that are building on your network!
This is completely unfair and UNETHICAL
1 customer, no matter how big or how much influence they have, should not be allowed to create CENTRALISATION on a supposedly DECENTRALIZED network!

I have been a community memeber since 2021 and I really am disappointed with what I have just read.
If we can now prioritise community built projects that provide TVL and support the network, this would be the main goal
We dont want to be forced out of this chain, but this is not fair on everyone else and especially for just 1 CUSTOMER

[SimiHunjan]

@tomachianura @Permabull313

In a recent update (v2.53.0) of Javascript SDK, we made a breaking change without following the right methodology. Your frustration regarding our previous response is valid. We truly appreciate you taking the time to share these concerns. Let us address and further clarify each issue.

The recent update to @hashgraph/sdk changed the return type of the signTransaction method from Uint8Array to SignatureMap without following proper deprecation protocols. 

• We take full responsibility in not following best practices set for introducing breaking changes to existing APIs. We try our best to refrain from making breaking changes that will impact the community, but while making them we definitely missed handling this appropriately. We should have done the following:
  • Provide advance notice to the community about upcoming changes and allow sufficient time for projects to test and update using beta versions
  • Highlighted the change prominently in our release notes with clear migration instructions for updating affected applications
• In the future, we will ensure we adhere to best practices if such a change is introduced
  • We will prioritize documenting a breaking change guide and deprecation policy that will be published for all projects to review

This change was done for the Transaction Tool which is an application used by the Hedera Governing Council. But even in that case, we should have followed the code update protocol as defined above.

We are happy to provide a custom build of the JS SDK that maintains the original return type and support it for the next 3 months, giving your project additional time to implement the changes.

Please let us know how we can best support your project best going forward.

[tomachianura]

@tomachianura @Permabull313

In a recent update (v2.53.0) of Javascript SDK, we made a breaking change without following the right methodology. Your frustration regarding our previous response is valid. We truly appreciate you taking the time to share these concerns. Let us address and further clarify each issue.

The recent update to @hashgraph/sdk changed the return type of the signTransaction method from Uint8Array to SignatureMap without following proper deprecation protocols. 

• We take full responsibility in not following best practices set for introducing breaking changes to existing APIs. We try our best to refrain from making breaking changes that will impact the community, but while making them we definitely missed handling this appropriately. We should have done the following:

  • Provide advance notice to the community about upcoming changes and allow sufficient time for projects to test and update using beta versions
  • Highlighted the change prominently in our release notes with clear migration instructions for updating affected applications

• In the future, we will ensure we adhere to best practices if such a change is introduced

  • We will prioritize documenting a breaking change guide and deprecation policy that will be published for all projects to review

This change was done for the Transaction Tool which is an application used by the Hedera Governing Council. But even in that case, we should have followed the code update protocol as defined above.

We are happy to provide a custom build of the JS SDK that maintains the original return type and support it for the next 3 months, giving your project additional time to implement the changes.

Please let us know how we can best support your project best going forward.

thanks for your answer @SimiHunjan.
to be fair, the update was introduced on the v2.51.0, so even earlier than you've reported.

Although i appreciate your response, and i want to give fully trust to you and your team, while keeping myself on an optimistic attitude for the future, i still don't understand why this change was needed, and most important i don't get why this change was in need to break the back compatibility and pushed you to fully ignore every single best practice whatsoever.

We at HbarSuite are using the native multisig service since 3 years now, we have even developed a multisig for customers and we use multisig-of-multisig for our smart-node engines, so i truly don't get why would you be in need to change the SDK so drastically for the Governing Council?

I mean, if we can do crazy complex operations on multisig, without ever asking you to change the SDK, how come you can't do the same when using the Transaction Tool?

So i kindly ask you, in name of transparency and to show respect towards our public ledger, our communities and our developers, can you please describe in details what the limitation was, and why you couldn't follow the standards procedure by deprecating the old method (while keeping it fully working) and just create a new method with a different name?

This is truly concerning, and forgive my insistence but you must understand that your decision and your action caused several damages to us and many other projects, damages which can be easily estimated in time and money spent.

we deserve a clear answer, we all deserve to know:

1. what the issue on the Tranasction Tool was, what the limitation was
2. how come you were not able to update the Transaction Tool, to make it use a newly named signTransactionWithSignatureMap instead of changing the logic inside the signTransaction method
3. why this was not openly communicated to the entire community
4. why this was not provided with at least 6 month notice
5. why didn't you consider how this selfish change could affect an entire community of projects and builders

we, the hbar holders, the hedera developers, the hedera projects, the hedera communities... we all deserve to know the truth behind such a poor choice.

[rbair23]

We at HbarSuite are using the native multisig service since 3 years now, we have even developed a multisig for customers and we use multisig-of-multisig for our smart-node engines, so i truly don't get why would you be in need to change the SDK so drastically for the Governing Council?

There was no need to break compatibility. We could have (and should have) just added a new method. And in fact, we've made things worse, because now the JS SDK returns something different from the signTransaction method than all other SDKs, which still return a byte[].

how come you were not able to update the Transaction Tool, to make it use a newly named signTransactionWithSignatureMap instead of changing the logic inside the signTransaction method

This should have been what was done.

The truth is, it was a poor decision and there is no justification. People make mistakes, and people learn from those mistakes. We can create a branch with the change reverted to give time to migrate. I wish we could just restore this method, but we cannot even do that without breaking people again :-(.

[tomachianura]

Thanks for the honest answer @rbair23.
Just to be clear: we do not need you to revert, the damage is already been caused and many projects spent money and time to fix your mistake and keep their engines up to date.

So I’m not looking for a justification here, but we need to understand why you did that on a first place.

Your colleague told us they were forced to take down this path due to some emergency needed by the Governing Council and the application they’re using.

So I’m asking again:

• why didn’t you guys ask them to change their code instead of breaking an entire sdk?
• why didn’t you consider the heavy consequences which comes out from such a decision?
• who was in charge for that? How come this PR was approved and merged?

Many project have been damaged by this, we have lost months of work and plenty of money.

So apologies are well accepted of course, and you guys still have our full trust that this won’t happen again in the future.

But don’t you think we all deserve a very detailed breakdown of what happened and why it happened, and especially considering you guys first told us it was some kind of mandatory emergency for a special customer, then you said it was for the governing council, and finally telling us it was just a poor choice? You’re going around in circles and keep changing the story of what happened and why it happened, it doesn’t work this way.

i will not let this convo die like this, without a detailed breakdown which could clarify for me and the entire Hedera community of developers and projects

I don’t see why retails always have to pay for mistakes we don’t have any responsibility for, it’s just unfair and can’t simply end up with “we’re sorry, it won’t happen again”.

I’m my humble opinion, either Hiero or Hedera or Swirlds or whoever is in charge should at least start some damage recovery initiative to support all those affected projects.

Again, we are Hsuite are fully opened to accept all the apologies, to keep giving you full trust this won’t happen again, and to build a better future by collaborating together.

But we’ve never been supported nor funded by Hedera at all, we’re 100% a community funded project, and we don’t believe it’s fair that we have to pay for the damages you’ve caused.

[sentx-io]

This change definitely breaks everything most developers on Hedera have worked with for the past years when it comes to the SDK. You absolutely need to fix the signTransaction return type breaking change. Please roll it back and instead provide an alternate version for your "new" client. Thanks.

[sentx-io]

You guys are telling me you broke ALL existing Hedera platforms that attempt to upgrade to the latest SDK, because this demo tool requested the signTransaction method to be changed?

https://github.com/hashgraph/hedera-transaction-tool/blob/main/README.md

I'm really trying to make sense of this.

[tomachianura]

You guys are telling me you broke ALL existing Hedera platforms that attempt to upgrade to the latest SDK, because this demo tool requested the signTransaction method to be changed?

https://github.com/hashgraph/hedera-transaction-tool/blob/main/README.md

I'm really trying to make sense of this.

Hello mate, unfortunately there’s no sense in what they’ve done.

Not only they did it because the “the special customer” (which turns out to be the governing council) was too lazy to change their DEMO APP, but on top of that they totally and deliberately bypassed all the best practices without caring at all about consequences.

On top of that, they’re now the only ones in the entire blockchain space who returns a signature map instead of a unit array, cause all the other sdks are respecting standards.

From a frustrated developer and project owner to another, if I can dare to give you a suggestion, do not upgrade until this is fixed.

But please, let’s all agree there’s no need to roll back the entire thing, cause rolling back would mean for Hsuite, Kabila and many others who wasted their own time and money to fix this that they did it in vain.

What shall be done at this point is exactly what I suggested at first, meaning they shall:

• only roll back the signTransaction method to return a Unit8Array
• at this point, to respect standards they should not even mark signTransaction as deprecated
• move their useless modifications into a new method called signTransactionWithSignautureMap
• finally mark signTransactionWithSignautureMap as deprecated or discouraged so to prevent new developers from using it.

Unfortunately, a part from the huge damage provoke to many projects who already went through the massive refactoring, they’ve also somehow managed to convince whoever is in charge of the hedera/walletconnect repository to change also the way walletconnect behaves on Hedera!!!

This means that, even though they fix this awful mistake here, you will still risk to face the same problem when updating your frontend application to the latest hedera/walletconnect sdk!!!

So at this point the damage is done my friend, and what ever they do will cost us more money and time to adapt (once again).

This is not how a blockchain and a public ledger shall behave.

Once again, I kindly and officially ask anyone in charge to give us a technical explanation and to proof why it was mandatory and urgent to break an entire SDK and the work of many builders due to an “emergency faced by a very high priority customer”.

I kindly ask you to stop going in circle changing the excuses you’ve provided so far (3-4 different excuses without any real technical explanations) and to detail a breakdown of what truly happened.

On top of that, I kindly ask you to think and to put in place a very generous and supportive recovery plan to financially support all those projects affected by your poor and unprofessional choice.

I’m sure @sentx-io and many others like Kabila will stand by this honest request in name of transparency and fairness.

We’re all here to support Hedera and its ecosystem, but it’s unsustainable for retails to keep paying for those mistakes, especially for those projects who never got funded by Hedera and they’re entirely community funded.

The delay you’re causing us when forcing us to upgrade our entire engines in order to keep them up to date, while following your non-best-practices is truly huge, as it’s huge the amount of time and money we have to invest into this.

Many projects and developers had already left, please be conscious that your attitude and behaviour is putting the entire ecosystem at risk.

[ed-marquez]

Hello Tomachi.
Thanks you for the feedback. I understand your frustration and that of other projects with this change. There was indeed an opportunity for this process and change to be executed in a better way from our end.

Reading the comments from Richard in this thread, it appears the team of contributors have admitted their mistake and offered alternatives to move forward in a productive and constructive way. Please note that a damage recovery initiative is not something that is feasible. In alignment with helping mitigate the impact of the changes, the team can offer guidance and suggestions and can also engage in conversation with you and your team to hear your recommendations for improvement.

As others in the thread have pointed out, I truly believe this was an honest mistake from which we all will learn and improve. We have a chance to do that collectively. Mistakes are unfortunate, but they're part of being human.

If you find it productive, I'd be happy to facilitate a call between your team and contributors in this thread to help us identify a way to move forward.

I also want to add that we do appreciate the time and work of the ecosystem projects, including HSuite. I am sorry for the impact these changes may have had on your work. We are committed to doing better in all areas, including learning from instances like this one.

Sincerely, Ed.