Skip to content

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

@algosdk/future

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.

Packages

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.

Long Term Plan

@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

  1. Publish @algosdk/future as a separate package from its own monorepo
  2. Include @algosdk/future packages in the upstream algorand/js-algorand-sdk repository and re-export them under a unstable namespace: algosdk.future
  3. Stabilize @algosdk/future packages and re-export them at the top level of algosdk and publish modular packages for today's algosdk functionality (@algosdk/transact, @algosdk/algod-api, etc.) that are also re-exported (non-breaking change)
  4. Deprecate algosdk.AtomicTransactionComposer in favor of @algosdk/future's TransactionComposer

Why Not AlgoKit?

@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.

Composer Migration

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.

extraFee and maxFee

AlgoKit

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

@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.

Sender and Signer

AlgoKit

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,
});

@algosdk/future

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
});

Resource Population

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,
});

Typed Client Migration

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.

App Creation, Factory & Deployer

Creation

In Utils, to create a new application you must use the app factory.

AlgoKit
import {
  HelloWorldClient,
  HelloWorldFactory,
} from "../contracts/clients/HelloWorld";

const factory = algorand.client.getTypedAppFactory(HelloWorldAppFactory);

const { appClient } = factory.send.create.createApplication({
  args: {
    arg1: 123,
    arg2: "foo",
  },
});
@algosdk/future

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.

Idempotent Deployer

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).

Overloaded ABI Methods

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.

Typed Composer

AlgoKit

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];

@algosdk/future

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].returnValue

If 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']

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages