`algopy.arc4`¶

Module Contents¶

Classes¶

`ARC4Client`	Used to provide typed method signatures for ARC-4 contracts
`ARC4Contract`	A contract that conforms to the ARC-4 ABI specification, functions decorated with `@abimethod` or `@baremethod` will form the public interface of the contract
`Address`	An alias for an array containing 32 bytes representing an Algorand address
`BigUFixedNxM`	An ARC-4 UFixed representing a decimal with the number of bits and precision specified.
`BigUIntN`	An ARC-4 UInt consisting of the number of bits specified.
`Bool`	An ARC-4 encoded bool
`Byte`	An ARC-4 alias for a UInt8
`DynamicArray`	A dynamically sized ARC-4 Array of the specified type
`DynamicBytes`	A variable sized array of bytes
`StaticArray`	A fixed length ARC-4 Array of the specified type and length
`String`	An ARC-4 sequence of bytes containing a UTF8 string
`Struct`	Base class for ARC-4 Struct types
`Tuple`	An ARC-4 ABI tuple, containing other ARC-4 ABI types
`UFixedNxM`	An ARC-4 UFixed representing a decimal with the number of bits and precision specified.
`UIntN`	An ARC-4 UInt consisting of the number of bits specified.

Functions¶

`abimethod`	Decorator that indicates a method is an ARC-4 ABI method.
`arc4_create`	Provides a typesafe and convenient way of creating an ARC4Contract via an inner transaction
`arc4_signature`	Returns the ARC-4 encoded method selector for the specified signature or abi method
`arc4_update`	Provides a typesafe and convenient way of updating an ARC4Contract via an inner transaction
`baremethod`	Decorator that indicates a method is an ARC-4 bare method.
`emit`	Emit an ARC-28 event for the provided event signature or name, and provided args.

Data¶

`UInt128`	An ARC-4 UInt128
`UInt16`	An ARC-4 UInt16
`UInt256`	An ARC-4 UInt256
`UInt32`	An ARC-4 UInt32
`UInt512`	An ARC-4 UInt512
`UInt64`	An ARC-4 UInt64
`UInt8`	An ARC-4 UInt8
`abi_call`	Provides a typesafe way of calling ARC-4 methods via an inner transaction

API¶

class algopy.arc4.ARC4Client¶: Used to provide typed method signatures for ARC-4 contracts

class algopy.arc4.ARC4Contract¶

A contract that conforms to the ARC-4 ABI specification, functions decorated with @abimethod or @baremethod will form the public interface of the contract

The approval_program will be implemented by the compiler, and route application args according to the ARC-4 ABI specification

The clear_state_program will by default return True, but can be overridden

class algopy.arc4.Address(value: algopy.Account | str | algopy.Bytes = ..., /)¶

An alias for an array containing 32 bytes representing an Algorand address

Initialization

If value is a string, it should be a 58 character base32 string, ie a base32 string-encoded 32 bytes public key + 4 bytes checksum. If value is a Bytes, it’s length checked to be 32 bytes - to avoid this check, use Address.from_bytes(...) instead. Defaults to the zero-address.

__bool__() → bool¶: Returns True if not equal to the zero address

__eq__(other: algopy.arc4.Address | algopy.Account | str) → bool¶: Address equality is determined by the address of another arc4.Address, Account or str

__getitem__(index: algopy.UInt64 | int) → algopy.arc4._TArrayItem¶: Gets the item of the array at provided index

__iter__() → Iterator[algopy.arc4._TArrayItem]¶: Returns an iterator for the items in the array

__ne__(other: algopy.arc4.Address | algopy.Account | str) → bool¶: Address equality is determined by the address of another arc4.Address, Account or str

__reversed__() → Iterator[algopy.arc4._TArrayItem]¶: Returns an iterator for the items in the array, in reverse order

__setitem__( index: algopy.UInt64 | int, value: algopy.arc4._TArrayItem, ) → algopy.arc4._TArrayItem¶: Sets the item of the array at specified index to provided value

copy() → Self¶: Create a copy of this array

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

property length: algopy.UInt64¶: Returns the current length of the array

property native: algopy.Account¶: Return the Account representation of the address after ARC-4 decoding

class algopy.arc4.BigUFixedNxM(value: str = '0.0', /)¶

An ARC-4 UFixed representing a decimal with the number of bits and precision specified.

Max size: 512 bits

Initialization

Construct an instance of UFixedNxM where value (v) is determined from the original decimal value (d) by the formula v = round(d * (10^M))

__bool__() → bool¶: Returns True if not equal to zero

__eq__(other: Self) → bool¶: Compare for equality, note both operands must be the exact same type

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

class algopy.arc4.BigUIntN(value: algopy.BigUInt | algopy.UInt64 | int = 0, /)¶

An ARC-4 UInt consisting of the number of bits specified.

Max size: 512 bits

Initialization

__bool__() → bool¶: Returns True if not equal to zero

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

property native: algopy.BigUInt¶: Return the BigUInt representation of the value after ARC-4 decoding

class algopy.arc4.Bool(value: bool = False, /)¶

An ARC-4 encoded bool

Initialization

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

property native: bool¶: Return the bool representation of the value after ARC-4 decoding

class algopy.arc4.Byte(value: algopy.BigUInt | algopy.UInt64 | int = 0, /)¶

An ARC-4 alias for a UInt8

Initialization

__bool__() → bool¶: Returns True if not equal to zero

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

property native: algopy.UInt64¶: Return the UInt64 representation of the value after ARC-4 decoding

class algopy.arc4.DynamicArray(*items: algopy.arc4._TArrayItem)¶

A dynamically sized ARC-4 Array of the specified type

Initialization

Initializes a new array with items provided

__add__( other: collections.abc.Iterable[algopy.arc4._TArrayItem], ) → algopy.arc4.DynamicArray[algopy.arc4._TArrayItem]¶: Concat two arrays together, returning a new array

__bool__() → bool¶: Returns True if not an empty array

__getitem__(index: algopy.UInt64 | int) → algopy.arc4._TArrayItem¶: Gets the item of the array at provided index

__iter__() → Iterator[algopy.arc4._TArrayItem]¶: Returns an iterator for the items in the array

__reversed__() → Iterator[algopy.arc4._TArrayItem]¶: Returns an iterator for the items in the array, in reverse order

__setitem__( index: algopy.UInt64 | int, value: algopy.arc4._TArrayItem, ) → algopy.arc4._TArrayItem¶: Sets the item of the array at specified index to provided value

append(item: algopy.arc4._TArrayItem, /) → None¶: Append an item to this array

copy() → Self¶: Create a copy of this array

extend(other: collections.abc.Iterable[algopy.arc4._TArrayItem], /) → None¶: Extend this array with the contents of another array

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

property length: algopy.UInt64¶: Returns the current length of the array

pop() → algopy.arc4._TArrayItem¶: Remove and return the last item of this array

class algopy.arc4.DynamicBytes¶

A variable sized array of bytes

__add__( other: collections.abc.Iterable[algopy.arc4._TArrayItem], ) → algopy.arc4.DynamicArray[algopy.arc4._TArrayItem]¶: Concat two arrays together, returning a new array

__bool__() → bool¶: Returns True if not an empty array

__getitem__(index: algopy.UInt64 | int) → algopy.arc4._TArrayItem¶: Gets the item of the array at provided index

__iter__() → Iterator[algopy.arc4._TArrayItem]¶: Returns an iterator for the items in the array

__reversed__() → Iterator[algopy.arc4._TArrayItem]¶: Returns an iterator for the items in the array, in reverse order

__setitem__( index: algopy.UInt64 | int, value: algopy.arc4._TArrayItem, ) → algopy.arc4._TArrayItem¶: Sets the item of the array at specified index to provided value

append(item: algopy.arc4._TArrayItem, /) → None¶: Append an item to this array

copy() → Self¶: Create a copy of this array

extend(other: collections.abc.Iterable[algopy.arc4._TArrayItem], /) → None¶: Extend this array with the contents of another array

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

property length: algopy.UInt64¶: Returns the current length of the array

property native: algopy.Bytes¶: Return the Bytes representation of the address after ARC-4 decoding

pop() → algopy.arc4._TArrayItem¶: Remove and return the last item of this array

class algopy.arc4.StaticArray¶

A fixed length ARC-4 Array of the specified type and length

__getitem__(index: algopy.UInt64 | int) → algopy.arc4._TArrayItem¶: Gets the item of the array at provided index

__iter__() → Iterator[algopy.arc4._TArrayItem]¶: Returns an iterator for the items in the array

__reversed__() → Iterator[algopy.arc4._TArrayItem]¶: Returns an iterator for the items in the array, in reverse order

__setitem__( index: algopy.UInt64 | int, value: algopy.arc4._TArrayItem, ) → algopy.arc4._TArrayItem¶: Sets the item of the array at specified index to provided value

copy() → Self¶: Create a copy of this array

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

property length: algopy.UInt64¶: Returns the current length of the array

class algopy.arc4.String(value: algopy.String | str = '', /)¶

An ARC-4 sequence of bytes containing a UTF8 string

Initialization

__bool__() → bool¶: Returns True if length is not zero

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

property native: algopy.String¶: Return the String representation of the UTF8 string after ARC-4 decoding

class algopy.arc4.Struct¶

Base class for ARC-4 Struct types

_replace(**kwargs: Any) → Self¶

Return a new instance of the struct replacing specified fields with new values.

Note that any mutable fields must be explicitly copied to avoid aliasing.

property bytes: algopy.Bytes¶: Get the underlying bytes[]

copy() → Self¶: Create a copy of this struct

classmethod from_bytes(value: algopy.Bytes | bytes, /) → Self¶: Construct an instance from the underlying bytes[] (no validation)

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

class algopy.arc4.Tuple(items: tuple[Unpack[algopy.arc4._TTuple]], /)¶

An ARC-4 ABI tuple, containing other ARC-4 ABI types

Initialization

Construct an ARC-4 tuple from a native Python tuple

__add__()¶: Return self+value.

__contains__()¶: Return bool(key in self).

__delattr__()¶: Implement delattr(self, name).

__dir__()¶: Default dir() implementation.

__eq__()¶: Return self==value.

__format__()¶

Default object formatter.

Return str(self) if format_spec is empty. Raise TypeError otherwise.

__ge__()¶: Return self>=value.

__getattribute__()¶: Return getattr(self, name).

__getitem__()¶: Return self[key].

__getstate__()¶: Helper for pickle.

__gt__()¶: Return self>value.

__hash__()¶: Return hash(self).

__iter__()¶: Implement iter(self).

__le__()¶: Return self<=value.

__len__()¶: Return len(self).

__lt__()¶: Return self<value.

__mul__()¶: Return self*value.

__ne__()¶: Return self!=value.

__new__()¶: Create and return a new object. See help(type) for accurate signature.

__reduce__()¶: Helper for pickle.

__reduce_ex__()¶: Helper for pickle.

__repr__()¶: Return repr(self).

__rmul__()¶: Return value*self.

__setattr__()¶: Implement setattr(self, name, value).

__sizeof__()¶: Size of object in memory, in bytes.

__str__()¶: Return str(self).

copy() → Self¶: Create a copy of this tuple

count()¶: Return number of occurrences of value.

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

index()¶

Return first index of value.

Raises ValueError if the value is not present.

property native: tuple[Unpack[algopy.arc4._TTuple]]¶: Convert to a native Python tuple - note that the elements of the tuple should be considered to be copies of the original elements

class algopy.arc4.UFixedNxM(value: str = '0.0', /)¶

An ARC-4 UFixed representing a decimal with the number of bits and precision specified.

Max size: 64 bits

Initialization

Construct an instance of UFixedNxM where value (v) is determined from the original decimal value (d) by the formula v = round(d * (10^M))

__bool__() → bool¶: Returns True if not equal to zero

__eq__(other: Self) → bool¶: Compare for equality, note both operands must be the exact same type

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

algopy.arc4.UInt128: TypeAlias¶

None

An ARC-4 UInt128

algopy.arc4.UInt16: TypeAlias¶

None

An ARC-4 UInt16

algopy.arc4.UInt256: TypeAlias¶

None

An ARC-4 UInt256

algopy.arc4.UInt32: TypeAlias¶

None

An ARC-4 UInt32

algopy.arc4.UInt512: TypeAlias¶

None

An ARC-4 UInt512

algopy.arc4.UInt64: TypeAlias¶

None

An ARC-4 UInt64

algopy.arc4.UInt8: TypeAlias¶

None

An ARC-4 UInt8

class algopy.arc4.UIntN(value: algopy.BigUInt | algopy.UInt64 | int = 0, /)¶

An ARC-4 UInt consisting of the number of bits specified.

Max Size: 64 bits

Initialization

__bool__() → bool¶: Returns True if not equal to zero

classmethod from_log(log: algopy.Bytes, /) → Self¶: Load an ABI type from application logs, checking for the ABI return prefix 0x151f7c75

property native: algopy.UInt64¶: Return the UInt64 representation of the value after ARC-4 decoding

algopy.arc4.abi_call: algopy.arc4._ABICallProtocolType¶

Ellipsis

Provides a typesafe way of calling ARC-4 methods via an inner transaction

def abi_call(
    self,
    method: Callable[..., _TABIResult_co] | str,
    /,
    *args: object,
    app_id: algopy.Application | algopy.UInt64 | int = ...,
    on_completion: algopy.OnCompleteAction = ...,
    approval_program: algopy.Bytes | bytes | tuple[algopy.Bytes, ...] = ...,
    clear_state_program: algopy.Bytes | bytes | tuple[algopy.Bytes, ...] = ...,
    global_num_uint: UInt64 | int = ...,
    global_num_bytes: UInt64 | int = ...,
    local_num_uint: UInt64 | int = ...,
    local_num_bytes: UInt64 | int = ...,
    extra_program_pages: UInt64 | int = ...,
    fee: algopy.UInt64 | int = 0,
    sender: algopy.Account | str = ...,
    note: algopy.Bytes | algopy.String | bytes | str = ...,
    rekey_to: algopy.Account | str = ...,
) -> tuple[_TABIResult_co, algopy.itxn.ApplicationCallInnerTransaction]: ...

PARAMETERS:

method: The name, method selector or Algorand Python method to call
app_id: Application to call, if 0 or not specified will create a new application
on_completion: OnCompleteAction value for the transaction. If not specified will be inferred from Algorand Python method where possible
approval_program: When creating or updating an application, the approval program
clear_state_program: When creating or updating an application, the clear state program
global_num_uint: When creating an application the number of global uints
global_num_bytes: When creating an application the number of global bytes
local_num_uint: When creating an application the number of local uints
local_num_bytes: When creating an application the number of local bytes
extra_program_pages: When creating an application the The number of extra program pages
fee: The fee to pay for the transaction, defaults to 0
sender: The sender address for the transaction
note: Note to include with the transaction
rekey_to: Account to rekey to

RETURNS:
If method references an Algorand Contract / Client or the function is indexed with a return type, then the result is a tuple containing the ABI result and the inner transaction of the call.

If no return type is specified, or the method does not have a return value then the result is the inner transaction of the call.

Examples:

# can reference another algopy contract method
result, txn = abi_call(HelloWorldContract.hello, arc4.String("World"), app=...)
assert result == "Hello, World"

# can reference a method selector
result, txn = abi_call[arc4.String]("hello(string)string", arc4.String("Algo"), app=...)
assert result == "Hello, Algo"

# can reference a method name, the method selector is inferred from arguments and return type
result, txn = abi_call[arc4.String]("hello", "There", app=...)
assert result == "Hello, There"

# calling a method without a return value
txn = abi_call(HelloWorldContract.no_return, arc4.String("World"), app=...)

algopy.arc4.abimethod( *, name: str = ..., create: Literal[allow, require, disallow] = 'disallow', allow_actions: collections.abc.Sequence[algopy.OnCompleteAction | Literal[NoOp, OptIn, CloseOut, UpdateApplication, DeleteApplication]] = ('NoOp',), readonly: bool = False, default_args: collections.abc.Mapping[str, str | algopy.arc4._ReadOnlyNoArgsMethod | object] = ..., ) → collections.abc.Callable[[collections.abc.Callable[algopy.arc4._P, algopy.arc4._R]], collections.abc.Callable[algopy.arc4._P, algopy.arc4._R]]¶

Decorator that indicates a method is an ARC-4 ABI method.

Parameters:

name – Name component of the ABI method selector. Defaults to using the function name.
create – Controls the validation of the Application ID. “require” means it must be zero, “disallow” requires it must be non-zero, and “allow” disables the validation.
allow_actions – A sequence of allowed On-Completion Actions to validate against.
readonly – If True, then this method can be used via dry-run / simulate.
default_args – Default argument sources for clients to use. For dynamic defaults, this can be the name of, or reference to a method member, or the name of a storage member. For static defaults, this can be any expression which evaluates to a compile time constant of the exact same type as the parameter.

algopy.arc4.arc4_create( method: collections.abc.Callable[algopy.arc4._P, algopy.arc4._TABIResult_co], /, *args: object, compiled: algopy.CompiledContract = ..., on_completion: algopy.OnCompleteAction = ..., fee: algopy.UInt64 | int = 0, sender: algopy.Account | str = ..., note: algopy.Bytes | bytes | str = ..., rekey_to: algopy.Account | str = ..., ) → tuple[algopy.arc4._TABIResult_co, algopy.itxn.ApplicationCallInnerTransaction]¶

Provides a typesafe and convenient way of creating an ARC4Contract via an inner transaction

Parameters:

method – An ARC-4 create method (ABI or bare), or an ARC4Contract with a single create method
args – ABI args for chosen method
compiled – If supplied will be used to specify transaction parameters required for creation, can be omitted if template variables are not used
on_completion – OnCompleteAction value for the transaction If not specified will be inferred from Algorand Python method where possible
fee – The fee to pay for the transaction, defaults to 0
sender – The sender address for the transaction
note – Note to include with the transaction
rekey_to – Account to rekey to

algopy.arc4.arc4_signature( signature: str | collections.abc.Callable[algopy.arc4._P, algopy.arc4._R], /, ) → algopy.Bytes¶: Returns the ARC-4 encoded method selector for the specified signature or abi method

algopy.arc4.arc4_update( method: collections.abc.Callable[algopy.arc4._P, algopy.arc4._TABIResult_co], /, *args: object, app_id: algopy.Application | algopy.UInt64 | int, compiled: algopy.CompiledContract = ..., fee: algopy.UInt64 | int = 0, sender: algopy.Account | str = ..., note: algopy.Bytes | bytes | str = ..., rekey_to: algopy.Account | str = ..., ) → tuple[algopy.arc4._TABIResult_co, algopy.itxn.ApplicationCallInnerTransaction]¶

Provides a typesafe and convenient way of updating an ARC4Contract via an inner transaction

Parameters:

method – An ARC-4 update method (ABI or bare), or an ARC4Contract with a single update method
args – ABI args for chosen method
app_id – Application to update
compiled – If supplied will be used to specify transaction parameters required for updating, can be omitted if template variables are not used
fee – The fee to pay for the transaction, defaults to 0
sender – The sender address for the transaction
note – Note to include with the transaction
rekey_to – Account to rekey to

algopy.arc4.baremethod( *, create: Literal[allow, require, disallow] = 'disallow', allow_actions: collections.abc.Sequence[algopy.OnCompleteAction | Literal[NoOp, OptIn, CloseOut, UpdateApplication, DeleteApplication]] = ..., ) → collections.abc.Callable[[collections.abc.Callable[[algopy.arc4._TARC4Contract], None]], collections.abc.Callable[[algopy.arc4._TARC4Contract], None]]¶

Decorator that indicates a method is an ARC-4 bare method.

There can be only one bare method on a contract for each given On-Completion Action.

Parameters:

create – Controls the validation of the Application ID. “require” means it must be zero, “disallow” requires it must be non-zero, and “allow” disables the validation.
allow_actions – Which On-Completion Action(s) to handle.

algopy.arc4.emit(event: str | algopy.arc4.Struct, /, *args: object) → None¶

Emit an ARC-28 event for the provided event signature or name, and provided args.

Parameters:

event –
Either an ARC-4 Struct, an event name, or event signature.
- If event is an ARC-4 Struct, the event signature will be determined from the Struct name and fields
- If event is a signature, then the following args will be typed checked to ensure they match.
- If event is just a name, the event signature will be inferred from the name and following arguments
args – When event is a signature or name, args will be used as the event data. They will all be encoded as single ARC-4 Tuple

Example:

from algopy import ARC4Contract, arc4


class Swapped(arc4.Struct):
    a: arc4.UInt64
    b: arc4.UInt64


class EventEmitter(ARC4Contract):
    @arc4.abimethod
    def emit_swapped(self, a: arc4.UInt64, b: arc4.UInt64) -> None:
        arc4.emit(Swapped(b, a))
        arc4.emit("Swapped(uint64,uint64)", b, a)
        arc4.emit("Swapped", b, a)

algopy.arc4¶

Module Contents¶

Classes¶

Functions¶

Data¶

API¶

`algopy.arc4`¶