This library is a light wrapper around algosdk to make it easier to interact with Algorand. The main features are
- Ergonomic ARC56-compatible transaction group composer
- ARC56 app client
- Typed ARC56 app client generator
- Localnet account generation and funding
Important
This library is a proof of concept and not recommended for production use. It is currently a testbed for features that may or may not be added to algosdk and/or algokit utils in the future.
| Package | Contents |
|---|---|
@algosdk/future |
Re-exports every package below |
@algosdk/transaction-composer |
Transaction composer, ARC56 types and utilities |
@algosdk/app-client |
ARC56 app client |
@algosdk/localnet |
Localnet account generation and funding |
@algosdk/typed-client-generator |
Typed ARC56 app client generator library and CLI. The generated clients include static types and concrete method implementations based on an ARC56 spec. |
Generated clients import from @algosdk/app-client and @algosdk/transaction-composer, so projects using them need both packages.
@algosdk/future represents features that will come to the SDK at a future date. Fast iteration and breakages are expected this early in development, hence @algosdk/future is a completely separate repo and package. Long term the plan is as follows
- Publish
@algosdk/futureas a separate package from its own monorepo - Include
@algosdk/futurepackages in the upstream algorand/js-algorand-sdk repository and re-export them under a unstable namespace:algosdk.future - Stabilize
@algosdk/futurepackages and re-export them at the top level ofalgosdkand publish modular packages for today'salgosdkfunctionality (@algosdk/transact,@algosdk/algod-api, etc.) that are also re-exported (non-breaking change) - Deprecate
algosdk.AtomicTransactionComposerin favor of@algosdk/future'sTransactionComposer
@algosdk/future is intentionally much simpler than AlgoKit. The abstractions are smaller and the amount of "magic" happening is lower. Some @algosdk/future interfaces are more verbose/explicit than AlgoKit Utils, but that is intentional. This makes it easier for agents to understand the library and for humans to review the code.
Additionally, @algosdk/future uses some new features of algod to do things in a different and breaking way. For example, transactions in @algosdk/future have a feePercent field rather than an extraFee or maxFee field. This allows simulate to be used to determine transaction fees rather than relying on hardcoded values.
The general pattern of the composer for both AlgoKit Utils and @algosdk/future is more or less the same. The composer takes in transaction parameters and can optionally do some of the mundane work (like setting suggestedParams) under the hood.
In AlgoKit utils you can use extraFee to hardcode extra fee to cover other transactions. A common use case is covering inner transactions on an app call.
// Send an app call with two inner transactions
composer
.addAppCallMethodCall({
sender,
appId,
args,
method,
staticFee: microAlgo(0),
})
.addPayment({
sender: feePayer,
receiver: feePayer,
amount: microAlgo(0),
extraFee: microAlgo(3_000), // 1_000 for the outer, 2_000 for the inners
});Alternatively, you can use the maxFee parameter in combination with coverAppCallInnerTransactionFees when sending. This will use simulate to add the required fee up to the required amount
composer
.addAppCallMethodCall({
sender,
appId,
args,
method,
staticFee: microAlgo(0),
})
.addPayment({
sender: feePayer,
receiver: feePayer,
amount: microAlgo(0),
maxFee: microAlgo(4_000), // 1_000 for this txn, 1_000 for the outer, 2_000 for the inners
});
composer.send({ coverAppCallInnerTransactionFees: true });The problem with this pattern is that it generally requires some assumptions to be made about fee prices which may change under congestion or with consensus updates.
@algosdk/future does not have a maxFee or extraFee field. Instead, each transaction has a feePercent parameter that defines what proportion of the group's total fee that transaction pays. The @algosdk/future composer uses simulate to determine the group's total fee, which is then split across the transactions according to their feePercent. This avoids any assumptions needing to be made about fee prices.
composer
.addAppCallMethodCall({
sender,
appId,
args,
method,
// No feePercent implies 0
})
.addPayment({
sender: feePayer,
receiver: feePayer,
amount: 0,
feePercent: 1, // cover all the fees in the group
});Note
The feePercent values across a group must sum to 1. If no transaction in the group specifies feePercent, they all default to 1 / n (an equal split). To make a specific transaction pay nothing, give it feePercent: 0. Transactions with a staticFee pay exactly that fee, and transactions with a staticUsage cover that much usage (their fee follows the current fee-per-usage); neither is ever adjusted. staticFee, staticUsage and feePercent are mutually exclusive. Pre-built transactions added with addTransaction always pay their own fixed fee and never contribute to other transactions. A transaction can also set maxUsage to cap the group usage its adjusted fee may pay for (derived from the current min fee). If its share of the group fee is more than that, buildGroup, execute and simulate throw. maxUsage cannot be combined with staticFee or staticUsage.
In AlgoKit Utils, the sender must be a string | Address. If the address is known by the AlgorandClient, then the TransactionSigner is implicit
const sender = algorand.account.random();
const composer = algorand.newGroup();
composer.addPayment({ sender, receiver, amount });For accounts AlgorandClient does not know about, the signer must be explicitly attached
const { activeAddress, transactionSigner } = useWallet();
composer.addPayment({
sender: activeAddress,
signer: transactionSigner,
receiver,
amount,
});In @algosdk/future, the sender must always be a ComposerSender, which is defined as AddressWithTransactionSigner & { emptyTxnSigner?: TransactionSigner }
const { activeAddress, transactionSigner } = useWallet();
composer.addPayment({
sender: { address: activeAddress, txnSigner: transactionSigner },
receiver,
amount,
});This interface is implemented by the return value of the addressWithSignersFromRaw... functions in algosdk. For example, to sign with a falcon account:
const { generateKey, signCompressed } = falcon1024;
const { publicKey, privateKey } = falcon1024.generateKey();
const falconSigningKey = {
falcon1024PublicKey: publicKey,
falcon1024Signer: async (bytesToSign) =>
falcon1024.signCompressed(privateKey, bytesToSign),
};
const sender =
algosdk.addressWithSignersFromRawFalcon1024Signer(falconSigningKey);
composer.addPayment({
sender,
receiver,
amount,
feePercent: 1, // @algosdk/future will use the sender.emptyTxnSigner during simulate to get the fees required for the pqsig
});Like utils, the @algosdk/future composer populates app call resources by default. The same simulation that determines fees also reports the accounts, apps, assets and boxes that app calls access without referencing, and the composer adds them to the group's reference arrays. App calls that use an access list are left untouched. To turn it off, construct the composer with populateAppCallResources: false:
const composer = new TransactionComposer({
getSuggestedParams,
populateAppCallResources: false,
});One of the main reasons projects use AlgoKit Utils is because of the typed client generator. @algosdk/future also offers a typed client generator that covers most of the features developers want (namely typed method calls) but there are some abstractions in the Utils version that are not implemented in @algosdk/future.
In Utils, to create a new application you must use the app factory.
import {
HelloWorldClient,
HelloWorldFactory,
} from "../contracts/clients/HelloWorld";
const factory = algorand.client.getTypedAppFactory(HelloWorldAppFactory);
const { appClient } = factory.send.create.createApplication({
args: {
arg1: 123,
arg2: "foo",
},
});In @algosdk/future, there is no Factory class and creation is done via a static method
import { HelloWorldClient } from "../contracts/clients/HelloWorld";
const { appClient } = await HelloWorldAppClient.create.createApplication({
algod: localnet.algod,
args: {
arg1: 123,
arg2: "foo",
},
sender,
});If the contract's bareActions.create is non-empty, the generated client also gets a create.bare that creates the app without an ABI call.
const { appClient, appId } = await HelloWorldClient.create.bare({
algod: localnet.algod,
sender,
templateVariables: { SOME_VALUE: 123n },
});The state schema comes from the ARC56 contract, and the number of extra program pages is derived from the compiled program sizes. Pass numGlobalInts, extraPages and friends to override either.
AlgoKit Utils includes abstractions for idempotent deployment. This feature uses the note field and indexer to find previous deployments of a contract. @algosdk/future does not include a similar feature. If you'd like to track previous deployments, you must implement your own way of recording past deployments (on or off chain).
Composer and app client methods accept a full ABI signature (such as "bar(uint64)uint64") or an algosdk.ABIMethod to select an exact overload. Bare names work only when unique; ambiguous names throw an error listing the available signatures.
Generated clients use full-signature keys for overloaded methods, for example appClient.call["bar(uint64)uint64"]({ sender, args: { a: 7n } }). The same keys apply to params, action-specific calls, create, return types, and non-void decodeReturnValue helpers. Unique methods retain their bare-name keys.
AlgoKit Utils' generated client includes a typed composer for composing a group with one or more typed method calls.
const result = await client
.newGroup()
.methodOne({ args: { arg1: 123 } })
.methodTwo({ args: { arg1: "foo" } })
.execute();
// Strongly typed as the return type of methodOne
const resultOfMethodOne = result.returns[0];
// Strongly typed as the return type of methodTwo
const resultOfMethodTwo = result.returns[1];With @algosdk/future, you can use the app client's params object to get the parameters to pass to a TransactionComposer. When calls are chained, the composer tracks each generated method's return type.
const composer = await new TransactionComposer(...)
.addMethodCall(client.params.methodOne({ args: { arg1: 123 } }))
.addMethodCall(client.params.methodTwo({ args: { arg1: 'foo' } }))
.execute(algod)
// Inferred as the return type of methodOne
const resultOfMethodOne = result.methodResults[0].returnValue
// Inferred as the return type of methodTwo
const resultOfMethodTwo = result.methodResults[1].returnValueIf for some reason you cannot chain the addMethodCalls calls with the execute, you can use the exported ${arc56.name}ReturnTypes from the generated client
import { HelloWorldClient, HelloWorldReturnTypes } from "../contracts/clients/HelloWorld";
const composer = await new TransactionComposer(...);
composer.addMethodCall(client.params.methodOne({ args: { arg1: 123 } }));
composer.addMethodCall(client.params.methodTwo({ args: { arg1: 'foo' } }));
const result = composer.execute(algod);
// methodResults will be unknown, so we must explicitly use `as`
const resultOfMethodOne = result.methodResults[0].returnValue as HelloWorldReturnTypes['methodOne']
const resultOfMethodTwo = result.methodResults[1].returnValue as HelloWorldReturnTypes['methodTwo']