docs: use algopy.Contract instead of algopy.ARC4Contract

boblat · boblat · commit 52dba73bf92f · 2025-11-24T15:53:22.000+08:00
diff --git a/README.md b/README.md
@@ -33,8 +33,8 @@ Alternatively, if you want to start from scratch you can do the following:
 4. Install Algorand Python into your project `poetry add algorand-python`
 5. Create a contract in a (e.g.) `contract.py` file:
     ```python
-    from algopy import ARC4Contract, arc4
-    class HelloWorldContract(ARC4Contract):
+    from algopy import Contract, arc4
+    class HelloWorldContract(Contract):
         @arc4.abimethod
         def hello(self, name: arc4.String) -> arc4.String:
             return "Hello, " + name
diff --git a/docs/index.md b/docs/index.md
@@ -19,8 +19,8 @@ Alternatively, if you want to start from scratch you can do the following:
 4. Install Algorand Python into your project `poetry add algorand-python`
 5. Create a contract in a (e.g.) `contract.py` file:
     ```python
-    from algopy import ARC4Contract, arc4
-    class HelloWorldContract(ARC4Contract):
+    from algopy import Contract, arc4
+    class HelloWorldContract(Contract):
         @arc4.abimethod
         def hello(self, name: arc4.String) -> arc4.String:
             return "Hello, " + name
diff --git a/docs/lg-arc28.md b/docs/lg-arc28.md
@@ -21,13 +21,13 @@ To emit an ARC-28 event in Algorand Python you can use the `emit` function, whic
 Here's an example contract that emits events:
 
 ```python
-from algopy import ARC4Contract, arc4
+from algopy import Contract, arc4
 
 class Swapped(arc4.Struct):
     a: arc4.UInt64
     b: arc4.UInt64
 
-class EventEmitter(ARC4Contract):
+class EventEmitter(Contract):
     @arc4.abimethod
     def emit_swapped(self, a: arc4.UInt64, b: arc4.UInt64) -> None:
         arc4.emit(Swapped(b, a))
diff --git a/docs/lg-arc4.md b/docs/lg-arc4.md
@@ -2,12 +2,12 @@
 
 [ARC-4](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md) defines a set of encodings and behaviors for authoring and interacting with an Algorand Smart Contract. It is not the only way to author a smart contract, but adhering to it will make it easier for other clients and users to interop with your contract.
 
-To author an arc4 contract you should extend the `ARC4Contract` base class.
+To author an arc4 contract you should extend the `Contract` base class.
 
 ```python
-from algopy import ARC4Contract
+from algopy import Contract
 
-class HelloWorldContract(ARC4Contract):
+class HelloWorldContract(Contract):
     ...
 ```
 
@@ -27,10 +27,10 @@ A method that should not be externally available can be optionally annotated wit
 Method docstrings will be used when outputting ARC-32 or ARC-56 application specifications, the following docstrings styles are supported ReST, Google, Numpydoc-style and Epydoc.
 
 ```python
-from algopy import ARC4Contract, subroutine, arc4, public
+from algopy import Contract, subroutine, arc4, public
 
 
-class HelloWorldContract(ARC4Contract):
+class HelloWorldContract(Contract):
     @arc4.abimethod(create="disallow", allow_actions=["NoOp", "OptIn"], name="external_name")
     def hello(self, name: arc4.String) -> arc4.String:
         return self.hello_impl() + name
@@ -51,7 +51,7 @@ class HelloWorldContract(ARC4Contract):
 
 Algorand Smart Contracts only have two possible programs that are invoked when making an ApplicationCall Transaction (`appl`). The "clear state" program which is called when using an OnComplete action of `ClearState` or the "approval" program which is called for all other OnComplete actions.
 
-Routing is required to dispatch calls handled by the approval program to the relevant ABI methods. When extending `ARC4Contract`, the routing code is automatically generated for you by the PuyaPy compiler.
+Routing is required to dispatch calls handled by the approval program to the relevant ABI methods. When extending `Contract`, the routing code is automatically generated for you by the PuyaPy compiler.
 
 ## Types
 
@@ -202,13 +202,13 @@ These types can only be used as parameters, and not as return types.
 from algopy import (
     Account,
     Application,
-    ARC4Contract,
+    Contract,
     Asset,
     arc4,
     gtxn,
 )
 
-class Reference(ARC4Contract):
+class Reference(Contract):
     @arc4.abimethod
     def with_transactions(
         self,
diff --git a/docs/lg-calling-apps.md b/docs/lg-calling-apps.md
@@ -17,9 +17,9 @@ If the ARC-4 method returns an ARC-4 result then the result will be a tuple of t
 If the ARC-4 method does not return a result, or if the result type is not fully qualified then just the inner transaction is returned.
 
 ```python
-from algopy import Application, ARC4Contract, String, arc4, subroutine
+from algopy import Application, Contract, String, arc4, subroutine
 
-class HelloWorld(ARC4Contract):
+class HelloWorld(Contract):
 
     @arc4.abimethod()
     def greet(self, name: String) -> String:
@@ -89,9 +89,9 @@ If the compiled programs and state allocation fields need to be customized (for
 this can be done by passing a [`algopy.CompiledContract`](#algopy.CompiledContract) via the `compiled` keyword argument.
 
 ```python
-from algopy import ARC4Contract, String, arc4, subroutine
+from algopy import Contract, String, arc4, subroutine
 
-class HelloWorld(ARC4Contract):
+class HelloWorld(Contract):
 
     @arc4.abimethod()
     def greet(self, name: String) -> String:
@@ -116,9 +116,9 @@ If the compiled programs need to be customized (for example due to [template var
 this can be done by passing a [`algopy.CompiledContract`](#algopy.CompiledContract) via the `compiled` keyword argument.
 
 ```python
-from algopy import Application, ARC4Contract, String, arc4, subroutine
+from algopy import Application, Contract, String, arc4, subroutine
 
-class NewApp(ARC4Contract):
+class NewApp(Contract):
 
     @arc4.abimethod()
     def greet(self, name: String) -> String:
diff --git a/docs/lg-compile.md b/docs/lg-compile.md
@@ -24,10 +24,10 @@ For example, the following contract has `UInt64` and `Bytes` template variables.
 
 ```{code-block} python
 :caption: templated_contract.py
-from algopy import ARC4Contract, Bytes, TemplateVar, UInt64, arc4
+from algopy import Contract, Bytes, TemplateVar, UInt64, arc4
 
 
-class TemplatedContract(ARC4Contract):
+class TemplatedContract(Contract):
 
     @arc4.abimethod
     def my_method(self) -> UInt64:
diff --git a/docs/lg-data-structures.md b/docs/lg-data-structures.md
@@ -83,15 +83,15 @@ However Puya will support reading and writing parts of a box
 
 ```python
 import typing
-from algopy import Box, FixedArray, Struct, UInt64, arc4, size_of
+from algopy import Box, Contract, FixedArray, Struct, UInt64, arc4, size_of
 
 
 
 class BigStruct(Struct):
     count: UInt64 # 8 bytes
     large_array: FixedArray[UInt64, typing.Literal[512]] # 4096 bytes
 
-class Contract(arc4.ARC4Contract):
+class Contract(Contract):
 
     def __init__(self) -> None:
         self.box = Box(BigStruct)
@@ -179,7 +179,7 @@ This is a regular python tuple
 ```python
 import algopy
 
-class SomeContract(algopy.arc4.ARC4Contract):
+class SomeContract(algopy.Contract):
     @algopy.arc4.abimethod()
     def get_array(self) -> algopy.ImmutableArray[algopy.UInt64]:
         arr = algopy.ReferenceArray[algopy.UInt64]()
diff --git a/docs/lg-migration-4-5.md b/docs/lg-migration-4-5.md
@@ -70,9 +70,9 @@ Individual methods can be forced to use the original behaviour by setting the `r
 on `arc4.abimethod` e.g.
 
 ```python
-from algopy import arc4, Account, Application, Asset
+from algopy import arc4, Account, Application, Asset, Contract
 
-class MyContract(arc4.ARC4Contract):
+class MyContract(Contract):
     @arc4.abimethod(resource_encoding="index")
     def my_abi_method(self, app: Application, asset: Asset, account: Account) -> None:
         ...
diff --git a/docs/lg-structure.md b/docs/lg-structure.md
@@ -91,7 +91,7 @@ consists of two distinct "programs"; an approval program, and a
 clear-state program. These are tied together in Algorand Python as a single class.
 
 All contracts must inherit from the base class `algopy.BaseContract` - either directly or indirectly,
-which can include inheriting from `algopy.ARC4Contract`.
+which can include inheriting from `algopy.ARC4Contract` or its alias, `algopy.Contract`.
 
 The life-cycle of a smart contract matches the semantics of Python classes when you consider
 deploying a smart contract as "instantiating" the class. Any calls to that smart contract are made
@@ -209,12 +209,12 @@ Some things to note:
 -   Any methods other than `__init__`, `approval_program` or `clear_state_program` must be decorated
     with `@subroutine`.
 
-### Example: Simplest possible `algopy.ARC4Contract` implementation
+### Example: Simplest possible `algopy.Contract` implementation
 
 And here is a valid ARC-4 contract:
 
 ```python
-class ABIContract(algopy.ARC4Contract):
+class ABIContract(algopy.Contract):
     pass
 ```
 
@@ -231,7 +231,7 @@ A default `clear_state_program` is implemented which always approves, but this c
 ```python
 import algopy
 
-class ARC4Counter(algopy.ARC4Contract):
+class ARC4Counter(algopy.Contract):
     def __init__(self) -> None:
         self.counter = algopy.UInt64(0)
 
@@ -255,9 +255,11 @@ Things to note here:
 -   The default options for `abimethod` is to only allow `NoOp` as an on-completion-action, so we
     don't need to check this manually.
 -   The current call count is returned from the `invoke` method.
--   Every method in an `ARC4Contract` except for the optional `__init__` and `clear_state_program`
-    methods must be decorated with one of `algopy.arc4.abimethod`, `algopy.arc4.baremethod`, or
-    `algopy.subroutine`. `subroutines` won't be directly callable through the default router.
+-   Every method in an `Contract` except for the optional `__init__` and `clear_state_program`
+    methods must be decorated with one of `algopy.arc4.baremethod`, `algopy.arc4.abimethod`
+    (or its alias, `public`), to indicate that they are externally callable. Other methods which won't
+    be directly callable through the default router can be optionally decorated with
+    `algopy.subroutine` decorator.
 
 See the [ARC-4 section](lg-arc4.md) of this language guide for more info on the above.
 
diff --git a/docs/lg-transactions.md b/docs/lg-transactions.md
@@ -29,7 +29,7 @@ For example to require a payment transaction in an ARC-4 ABI method:
 import algopy
 
 
-class MyContract(algopy.ARC4Contract):
+class MyContract(algopy.Contract):
 
     @algopy.arc4.abimethod()
     def process_payment(self, payment: algopy.gtxn.PaymentTransaction) -> None:
diff --git a/docs/lg-types.md b/docs/lg-types.md
@@ -325,11 +325,11 @@ value. This can be declared using the `TemplateVar[TYPE]` type where `TYPE` is t
 Algorand Python type that it will be interpreted as.
 
 ```python
-from algopy import BigUInt, Bytes, TemplateVar, UInt64, arc4
+from algopy import BigUInt, Bytes, Contract, TemplateVar, UInt64, arc4
 from algopy.arc4 import UInt512
 
 
-class TemplateVariablesContract(arc4.ARC4Contract):
+class TemplateVariablesContract(Contract):
     @arc4.abimethod()
     def get_bytes(self) -> Bytes:
         return TemplateVar[Bytes]("SOME_BYTES")
@@ -406,7 +406,7 @@ It should be noted, however, that all the validation methods the Puya compiler d
 For example, given the following contract:
 
 ```py
-class BoxReadWrite(ARC4Contract):
+class BoxReadWrite(Contract):
 
     def __init__(self) -> None:
         self.acct_box = Box(Account)
@@ -423,7 +423,7 @@ class BoxReadWrite(ARC4Contract):
 One can be sure that the value in `acctBox` is always valid because the only source of the value is an ABI argument (`acct` in `writeToBox`). If validation was disabled, however, then one cannot trust that it is properly encoded and should perform a manual validation if required:
 
 ```py
-class BoxReadWrite(ARC4Contract):
+class BoxReadWrite(Contract):
 
     def __init__(self):
         self.acct_box = Box(Account)
diff --git a/security/001-arc4-encoding.md b/security/001-arc4-encoding.md
@@ -51,15 +51,15 @@ Your contract is vulnerable to the fixed-length argument overflow if the followi
 Example 1: Fixed-Length Argument Overflow
 
 ```py
-from algopy import arc4, UInt64
+from algopy import arc4, Contract, UInt64
 from typing import Literal
 
 # Type alias for a 32-byte static array
 StaticBytes32 = arc4.StaticArray[arc4.Byte, Literal[32]]
 
 SUPER_IMPORTANT_VALUE = 42
 
-class VulnerableContract(arc4.ARC4Contract):
+class VulnerableContract(Contract):
     @arc4.abimethod
     def static_value(self, static_bytes: StaticBytes32) -> arc4.UInt64:
         # ⚠️ VULNERABLE: If static_bytes is more than 32 bytes,
@@ -73,13 +73,13 @@ class VulnerableContract(arc4.ARC4Contract):
 Example 2: Fixed-Length ABI Return Overflow
 
 ```py
-from algopy import arc4, UInt64
+from algopy import arc4, Contract, UInt64
 from typing import Literal
 
 StaticBytes32 = arc4.StaticArray[arc4.Byte, Literal[32]]
 SUPER_IMPORTANT_VALUE = 42
 
-class VulnerableContract(arc4.ARC4Contract):
+class VulnerableContract(Contract):
     @arc4.abimethod
     def malicious_contract_return(self, malicious_app_id: UInt64) -> arc4.UInt64:
         # Call external contract that claims to return 32 bytes
@@ -110,7 +110,7 @@ Your contract may be vulnerable to “hidden” values in dynamic arrays if the
 Example “Hidden” Dynamic Array Values
 
 ```py
-class HiddenValues(ARC4Contract):
+class HiddenValues(Contract):
     even_numbers: GlobalState[DynamicArray[UInt64]]
 
     def __init__(self) -> None:
@@ -142,7 +142,7 @@ Your contract may panic at unexpected times if the following is true:
 3. You save the value in the contract state and try to use it in a subsequent call.
 
 ```py
-class InvalidEncoding(ARC4Contract):
+class InvalidEncoding(Contract):
     numbers: Box[DynamicArray[UInt64]]
     numbers_sum: Box[UInt64]
 
diff --git a/security/002-missing-assert.md b/security/002-missing-assert.md
@@ -40,9 +40,9 @@ The following examples show how the vulnerability would appear in a contract.
 #### Example 1: global flag check
 
 ```py
-from algopy import ARC4Contract, arc4
+from algopy import Contract, arc4
 
-class VulnerableContract(ARC4Contract):
+class VulnerableContract(Contract):
     @arc4.abimethod(create="require")
     def create(self, value: bool) -> None:
         self.global_flag = value
diff --git a/stubs/algopy-stubs/_base_contract.pyi b/stubs/algopy-stubs/_base_contract.pyi
@@ -55,7 +55,7 @@ class BaseContract(abc.ABC):
          Will affect the output TEAL file name if there are multiple non-abstract contracts
          in the same file.
 
-         If the contract is a subclass of algopy.ARC4Contract, `name` will also be used as the
+         If the contract is a subclass of algopy.Contract, `name` will also be used as the
          contract name in the ARC-32 application.json, instead of the class name.
 
         :param scratch_slots:
diff --git a/stubs/algopy-stubs/arc4.pyi b/stubs/algopy-stubs/arc4.pyi
@@ -720,9 +720,9 @@ def arc4_create(
     rekey_to: algopy.Account | str = ...,
 ) -> tuple[_TABIResult_co, algopy.itxn.ApplicationCallInnerTransaction]:
     """
-    Provides a typesafe and convenient way of creating an ARC4Contract via an inner transaction
+    Provides a typesafe and convenient way of creating a Contract via an inner transaction
 
-    :param method: An ARC-4 create method (ABI or bare), or an ARC4Contract with a single create method
+    :param method: An ARC-4 create method (ABI or bare), or a Contract with a single create method
     :param args: ABI args for chosen method
     :param compiled: If supplied will be used to specify transaction parameters required for creation,
                      can be omitted if template variables are not used
@@ -761,9 +761,9 @@ def arc4_update(
     reject_version: algopy.UInt64 | int = ...,
 ) -> tuple[_TABIResult_co, algopy.itxn.ApplicationCallInnerTransaction]:
     """
-    Provides a typesafe and convenient way of updating an ARC4Contract via an inner transaction
+    Provides a typesafe and convenient way of updating a Contract via an inner transaction
 
-    :param method: An ARC-4 update method (ABI or bare), or an ARC4Contract with a single update method
+    :param method: An ARC-4 update method (ABI or bare), or a Contract with a single update method
     :param args: ABI args for chosen method
     :param app_id: Application to update
     :param compiled: If supplied will be used to specify transaction parameters required for updating,
