Invoking Soroban contract with Stellar Python SDK

[overcat]

Initial support for Soroban has now been added to the Stellar Python SDK, and I'm happy to share an example here to show how to use it.

Warning
Please note that support for Soroban is still under development, so breaking changes may occur.

Prerequisite

1. Follow this tutorial to deploy the Hello World contract.
2. Install Stellar Python SDK from the soroban branch: pip install git+https://github.com/StellarCN/py-stellar-base.git@soroban
3. Modify the necessary parameters in this script, then run it.

Code Example

Copy from https://github.com/StellarCN/py-stellar-base/blob/soroban/examples/soroban_invoke_contract_function.py

import time

from stellar_sdk import Network, Keypair, TransactionBuilder
from stellar_sdk import xdr as stellar_xdr
from stellar_sdk.soroban import SorobanServer
from stellar_sdk.soroban.soroban_rpc import GetTransactionStatus
from stellar_sdk.soroban.types import Symbol

# TODO: You need to replace the following parameters according to the actual situation
secret = "SAAPYAPTTRZMCUZFPG3G66V4ZMHTK4TWA6NS7U4F7Z3IMUD52EK4DDEV"
rpc_server_url = "https://rpc-futurenet.stellar.org:443/"
contract_id = "14d04b99ac22a080c81c607b7032e887aa7ad8c2192c3b5ee47e3c09f21da5dd"
network_passphrase = Network.FUTURENET_NETWORK_PASSPHRASE

kp = Keypair.from_secret(secret)
soroban_server = SorobanServer(rpc_server_url)
source = soroban_server.load_account(kp.public_key)

# Let's build a transaction that invokes the `hello` function.
tx = (
    TransactionBuilder(source, network_passphrase)
    .set_timeout(300)
    .append_invoke_contract_function_op(
        contract_id=contract_id,
        function_name="hello",
        parameters=[Symbol("world")],
        source=kp.public_key,
    )
    .build()
)

simulate_transaction_data = soroban_server.simulate_transaction(tx)
print(f"simulated transaction: {simulate_transaction_data}")

print(f"setting footprint and signing transaction...")
assert simulate_transaction_data.results is not None
tx.set_footpoint(simulate_transaction_data.results[0].footprint)
tx.sign(kp)

send_transaction_data = soroban_server.send_transaction(tx)
print(f"sent transaction: {send_transaction_data}")

while True:
    print("waiting for transaction to be confirmed...")
    get_transaction_data = soroban_server.get_transaction(send_transaction_data.hash)
    if get_transaction_data.status != GetTransactionStatus.NOT_FOUND:
        break
    time.sleep(3)

print(f"transaction: {get_transaction_data}")

if get_transaction_data.status == GetTransactionStatus.SUCCESS:
    assert get_transaction_data.result_meta_xdr is not None
    transaction_meta = stellar_xdr.TransactionMeta.from_xdr(
        get_transaction_data.result_meta_xdr
    )
    result = transaction_meta.v3.tx_result.result.results[0].tr.invoke_host_function_result.success  # type: ignore
    output = [x.sym.sc_symbol.decode() for x in result.vec.sc_vec]  # type: ignore
    print(f"transaction result: {output}")

Expected output

simulated transaction: footprint='AAAAAQAAAAbKCOosGb1H2eBN4MyG4UQIZvbH+GNAlYcsOAAOGny82QAAAAMAAAADAAAAAA==' cost=Cost(cpu_insns='146295', mem_bytes='2844') results=[TransactionStatusResult(xdr='AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAFSGVsbG8AAAAAAAAFAAAABXdvcmxkAAAA')] error=None latest_ledger=50768
setting footprint and signing transaction...
sent transaction: id='60a41f8bfde50c6f1a0f22d15863ad96d96f43faa20ff9d6f59788873392c5ec' status=<TransactionStatus.PENDING: 'pending'>
waiting for transaction to be confirmed...
waiting for transaction to be confirmed...
transaction status: id='60a41f8bfde50c6f1a0f22d15863ad96d96f43faa20ff9d6f59788873392c5ec' status=<TransactionStatus.SUCCESS: 'success'> results=[TransactionStatusResult(xdr='AAAABAAAAAEAAAAAAAAAAgAAAAUAAAAFSGVsbG8AAAAAAAAFAAAABXdvcmxkAAAA')]
transaction result: ['Hello', 'world']

[rice2000]

This is awesome! Thanks for submitting! We will start reviewing submissions for rewards this week, and will check in on this thread with any questions, feedbacks, or updates. But yeah: great submission!

[achallagundla]

Heya Overcat,
Congratulations! Your contribution to Sorobanathon: First Light has been accepted! 🎉
Your submission may qualify for a reward of 3000 XLM! One last step: to receive that reward, please fill out this form completely and accurately.

Please let us know if you have any questions. (You can also message me on discord @ anuxhya)

All the best,
Anuhya

[leighmcculloch]

@overcat Thanks for exploring how the Python SDK would expose invocations.

One thing I noticed is that the append_invoke_host_function_op supports appending only one type of host function, the HOST_FN_CALL type. It'd be useful if the other host function types can be called too, for things like deploying contracts.

I really like that the append_invoke_host_function_op hides all of the complexity of how to actually construct a HOST_FN_CALL.

Maybe the current function could be append_invoke_contract_function, and a new function that does deployment could be append_deploy_contract? Both could continue to hide the complexity of how to construct them.

[overcat]

Yes, I will add the function to deployment contracts soon.

[overcat]

Support for deploying contracts has been added, here is an example.

[leighmcculloch]

A very nice simple interface 👏🏻

[overcat]

The Python SDK now supports building the signatures required to call contract functions.

from stellar_sdk import Network, Keypair
from stellar_sdk.soroban_types import Ed25519Identifier, SignaturePayload
from stellar_sdk.soroban_types import Int128

secret = "SAAPYAPTTRZMCUZFPG3G66V4ZMHTK4TWA6NS7U4F7Z3IMUD52EK4DDEV"
network_passphrase = Network.FUTURENET_NETWORK_PASSPHRASE

kp = Keypair.from_secret(secret)
action_name = "increment"
contract_id = "3770d1476b54e803be56832e3c461daaec862e3a0620cf53a1c9f4028809d38b"
nonce = Int128(0)
signature_payload = SignaturePayload(
    network_passphrase, contract_id, action_name, [Ed25519Identifier(kp), nonce]
)
ed25519_signature = signature_payload.ed25519_sign(kp)
print(f"signature: {ed25519_signature.signature.hex()}")
print(f"signature object: {ed25519_signature._to_xdr_sc_val().to_xdr()}")

You can find an example here: https://github.com/StellarCN/py-stellar-base/blob/soroban/examples/soroban_invoke_auth_advanced_contract.py

[overcat]

In addition, we have introduced some classes to help make it easier to build the parameters needed to call contract functions. They are currently located in stellar_sdk.soroban_types, which can free users from constructing SCObject (in most scenarios), and I am considering adding more related classes.

After introducing these classes:

account = AccountIdentifier(kp)

Before introducing these classes:

account = stellar_xdr.SCVal(
    stellar_xdr.SCValType.SCV_OBJECT,
    obj=stellar_xdr.SCObject(
        stellar_xdr.SCObjectType.SCO_VEC,
        vec=stellar_xdr.SCVec(
            sc_vec=[
                stellar_xdr.SCVal(
                    stellar_xdr.SCValType.SCV_SYMBOL,
                    sym=stellar_xdr.SCSymbol("Account".encode()),
                ),
                stellar_xdr.SCVal(
                    stellar_xdr.SCValType.SCV_OBJECT,
                    obj=stellar_xdr.SCObject(
                        stellar_xdr.SCObjectType.SCO_ACCOUNT_ID,
                        account_id=kp.xdr_account_id(),
                    ),
                ),
            ]
        ),
    ),
)

[overcat]

Stellar Quest 5 is an excellent material to learn about Soroban, and I've prepared Python solutions to help you understand how to use the Python SDK.

Check out: https://github.com/overcat/stellar-quest-solutions

[overcat]

If you are a developer looking to add support for Soroban in other SDKs, here is a checklist to help you get started. This checklist will also be updated as development progresses. Please let me know if you have any suggestions.

Please note that the implementation of Python is still in progress and the code implementation may change at any time.

Checklist:

• Update the XDR file. You can find the latest XDR file here: https://github.com/stellar/stellar-xdr/tree/next

• Add support for the InvokeHostFunction Operation:

  • https://github.com/StellarCN/py-stellar-base/blob/soroban/stellar_sdk/operation/operation.py
  • https://github.com/stellar/stellar-xdr/blob/026c9cd074bdb28ddde8ee52f2a4502d9e518a09/Stellar-transaction.x#L533-L539

• (Optional) I have added some helper functions to help users more easily build the InvokeHostFunction Operation: https://github.com/StellarCN/py-stellar-base/blob/0f328df534df479ae323f476d314d10b5462f59c/stellar_sdk/transaction_builder.py#L1201-L1372

• Add support for Soroban RPC:

  • https://github.com/StellarCN/py-stellar-base/tree/soroban/stellar_sdk/soroban
  • https://github.com/stellar/soroban-tools/blob/cab4da5d4e6c219d070fa70fc5aec69201f0de53/cmd/soroban-rpc/internal/jsonrpc.go

• (Optional) I have added a series of data types to help users more easily build the parameters required to call a contract, which correspond one-to-one with the data types in the Rust Soroban SDK: https://github.com/StellarCN/py-stellar-base/tree/soroban/stellar_sdk/soroban_types There is a new proposal about Auth here, so I suggest you watch and not implement it now.

• Add support for Soroban Signature:

  • https://soroban.stellar.org/docs/examples/auth-advanced
  • https://github.com/StellarCN/py-stellar-base/blob/soroban/stellar_sdk/soroban_types/signature_payload.py
  • https://github.com/stellar/rs-soroban-sdk/blob/main/soroban-auth/src/public_types.rs#L87-L117

• Add support for contract strkey: feat: add contract strkey support StellarCN/py-stellar-base#670

• Add support for Auth Next:

  • https://soroban.stellar.org/docs/learn/authorization
  • feat: add support for Auth Next. StellarCN/py-stellar-base#702

[christian-rogobete]

Hello @overcat, thank you for providing this guide. It helped me a lot to add Soroban support to my SDKs.

[overcat]

Stellar Python SDK now supports Soroban Preview 7, which includes support for Auth Next.

An example of building Contract Auth.
https://github.com/StellarCN/py-stellar-base/blob/soroban/examples/soroban_auth_atomic_swap.py

alice_root_invocation = AuthorizedInvocation(
    contract_id=atomic_swap_contract_id,
    function_name="swap",
    args=[
        Bytes(binascii.unhexlify(native_token_contract_id)),  # token_a
        Bytes(binascii.unhexlify(cat_token_contract_id)),  # token_b
        Int128(1000),  # amount_a
        Int128(4500),  # min_b_for_a
    ],
    sub_invocations=[
        AuthorizedInvocation(
            contract_id=native_token_contract_id,
            function_name="incr_allow",
            args=[
                Address(alice_kp.public_key),  # owner
                Address.from_raw_contract(atomic_swap_contract_id),
                Int128(1000),
            ],
            sub_invocations=[],
        )
    ],
)
alice_contract_auth = ContractAuth(
    address=Address(alice_kp.public_key),
    nonce=alice_nonce,
    root_invocation=alice_root_invocation,
)
alice_contract_auth.sign(alice_kp, network_passphrase)

[christian-rogobete]

Hello @overcat, this is very nice, thank you. Did you find out why the transaction fails if the invoker is the same as the submitter in the soroban_auth_with_stellar_account example. I have the same issue.

[overcat]

Yes, it's not a bug, check https://discord.com/channels/897514728459468821/1078208197283807305

[christian-rogobete]

Thank you, that helps me. I didn't think about the footprint either.