> ## Documentation Index
> Fetch the complete documentation index at: https://developers.stellar.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Simple Account

> A minimal contract account secured by a single ed25519 public key.

This example implements the smallest possible [contract account](https://developers.stellar.org/docs/learn/glossary.md#contract-account): each `require_auth` call delegates to one ed25519 public key. It shows how to store that key, run `__check_auth`, and surface authorization failures. Use this as the baseline before moving to the [Complex Account example](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/complex-account.md) for multisig or policy enforcement.

> [!CAUTION]
>
> Implementing a contract account requires a very good understanding of authentication and authorization and requires rigorous testing and review. The example here is *not* a full-fledged account contract - use it as an API reference only.

> [!WARNING]
>
> While contract accounts are supported by the Stellar protocol and Soroban SDK, the full client support (such as transaction simulation) is still under development.

[![Open in Codespaces](https://github.com/codespaces/badge.svg)][open-in-github-codespaces]

[![Open in Codeanywhere](https://codeanywhere.com/img/open-in-codeanywhere-btn.svg)][open-in-code-anywhere]

[open-in-github-codespaces]: https://github.com/codespaces/new?repo=stellar/soroban-examples&editor=web

[open-in-code-anywhere]: https://app.codeanywhere.com/#https://github.com/stellar/soroban-examples

## Run the Example

1. Finish the [Setup] checklist to install the Stellar CLI, Rust target, and required environment variables.
2. Clone the `soroban-examples` repository at the `main` branch:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone -b main https://github.com/stellar/soroban-examples
```

3. If you prefer not to install anything locally, launch the repo in [GitHub Codespaces][open-in-github-codespaces] or [Codeanywhere][open-in-code-anywhere].

Run the tests from the `simple_account` directory:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
cd simple_account
cargo test
```

Expected output:

```
running 1 test
test test::test_account ... ok
```

[setup]: https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup.md

## How it Works

Open `simple_account/src/lib.rs`. The contract keeps one piece of state: the owner's ed25519 public key.

### Initialize the owner

```rust title="simple_account/src/lib.rs" theme={"theme":{"light":"github-light","dark":"github-dark"}}
#[contracttype]
#[derive(Clone)]
pub enum DataKey {
    Owner,
}

#[contractimpl]
impl SimpleAccount {
    pub fn __constructor(env: Env, public_key: BytesN<32>) {
        if env.storage().instance().has(&DataKey::Owner) {
            panic!("owner is already set");
        }
        env.storage().instance().set(&DataKey::Owner, &public_key);
    }
```

`__constructor` runs once, at deployment, to persist the owner's public key.

### Implement `__check_auth`

```rust title="simple_account/src/lib.rs" theme={"theme":{"light":"github-light","dark":"github-dark"}}
    #[allow(non_snake_case)]
    pub fn __check_auth(
        env: Env,
        signature_payload: BytesN<32>,
        signature: BytesN<64>,
        _auth_context: Vec<Context>,
    ) {
        let public_key: BytesN<32> = env
            .storage()
            .instance()
            .get(&DataKey::Owner)
            .unwrap();
        env.crypto()
            .ed25519_verify(&public_key, &signature_payload.into(), &signature);
    }
}
```

`__check_auth` runs whenever another contract invokes `require_auth` on this contract address. The implementation loads the stored key, verifies the signature, and panics on failure so the upstream `require_auth` call rejects. Once you need multiple keys or policy logic, follow the same pattern shown in Complex Account.

## Tests

Open `simple_account/src/test.rs`. `__check_auth` is not exposed as a regular entry point, so tests call `env.try_invoke_contract_check_auth` to emulate the Soroban host and exercise the same path Soroban runs during `require_auth`.

```rust title="simple_account/src/test.rs" theme={"theme":{"light":"github-light","dark":"github-dark"}}
#[test]
fn test_account() {
    let env = Env::default();

    let signer = Keypair::generate(&mut thread_rng());
    let public_key: BytesN<32> = signer.public.to_bytes().into_val(&env);
    let contract_id = env.register(SimpleAccount, SimpleAccountArgs::__constructor(&public_key));
    let account_contract = SimpleAccountClient::new(&env, &contract_id);

    let payload = BytesN::random(&env);
    env.try_invoke_contract_check_auth::<Error>(
        &account_contract.address,
        &payload,
        sign(&env, &signer, &payload),
        &vec![&env],
    )
    .unwrap();

    assert!(env
        .try_invoke_contract_check_auth::<Error>(
            &account_contract.address,
            &payload,
            BytesN::<64>::random(&env).into(),
            &vec![&env],
        )
        .is_err());
}
```

`try_invoke_contract_check_auth` mimics the host path for `require_auth`, so the test proves both the success case and a failure case with random bytes.

Follow the same structure for any account:

* create a keypair and store the expected signer (for example, via `__constructor`)
* call `try_invoke_contract_check_auth` with a valid signature and assert it succeeds
* call it again with an invalid signature or payload and assert it fails

## Build the Contract

To produce the Wasm executable, run:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
stellar contract build
# add --package soroban-simple-account-contract when building inside the soroban-examples workspace
```

The compiled file appears at `target/wasm32v1-none/release/simple_account.wasm` (the exact filename depends on your crate name).

## Further Reading

* [Complex account example] – adds multisig support and spend limits.
* [BLS signature contract](https://developers.stellar.org/docs/build/smart-contracts/example-contracts/bls-signature.md) – demonstrates custom signature schemes inside `__check_auth`.

[Complex account example]: https://developers.stellar.org/docs/build/smart-contracts/example-contracts/complex-account.md

[simple account example]: https://github.com/stellar/soroban-examples/tree/main/simple_account