Skip to content
Merged
Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
72f7593
feat(examples): add a SEP-40 consumer contract
hpmaxi Nov 10, 2026
c8afda9
test(harness): read the feed from a consumer
hpmaxi Nov 11, 2026
ab178a4
fix(harness): scope force and check event payload
hpmaxi Nov 11, 2026
e24abeb
style(harness): shorten the send comment
hpmaxi Nov 11, 2026
e7d2c22
docs: record the SEP-40 consumer on testnet
hpmaxi Nov 11, 2026
707f2c6
docs: say the consumer run can attest a NAV
hpmaxi Nov 11, 2026
2416c10
test(examples): check temporary storage is empty
hpmaxi Nov 11, 2026
21aa722
fix(examples): refuse a non-contract feed
hpmaxi Nov 11, 2026
976c9dd
docs: correct the recorded SEP-40 no-price run
hpmaxi Nov 11, 2026
2850566
refactor(harness): drop unused recordedEvent
hpmaxi Nov 11, 2026
350d1b0
refactor(harness): merge wasmOf and exampleWasmOf
hpmaxi Nov 11, 2026
cc698e3
test(harness): verify the sent consumer event too
hpmaxi Nov 11, 2026
b482ccb
docs: note the example in the doc-size test
hpmaxi Nov 11, 2026
d63f656
docs(harness): say test:sep40 attests a stale NAV
hpmaxi Nov 11, 2026
0a3cd79
fix(harness): attest on a fresh network
hpmaxi Nov 11, 2026
fc675a9
docs: record a SEP-40 price read on testnet
hpmaxi Nov 11, 2026
ee96ae3
docs: link the feed design, not a decision record
hpmaxi Nov 13, 2026
0c8e49f
test(harness): read contract events of a sent tx
hpmaxi Nov 13, 2026
6079c4b
docs(examples): leave the price age to callers
hpmaxi Nov 13, 2026
39be5b2
Merge commit 'e05e4efaad7c04af293d7cf1cba4c74ddefc99b0' into feat/237…
hpmaxi Nov 13, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -299,8 +299,9 @@ jobs:
echo "Expected $INDEX to exist and be non-empty after client generation."
exit 1
fi
# Count one exported const per contract
EXPECTED=$(find contracts -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')
# Count one exported const per contract; the scaffold deploys every
# workspace contract, examples included.
EXPECTED=$(find contracts examples -mindepth 1 -maxdepth 1 -type d | wc -l | tr -d ' ')
ACTUAL=$(grep -c "^export const " "$INDEX" || true)
if [ "$ACTUAL" -ne "$EXPECTED" ]; then
echo "Expected $EXPECTED client(s) in $INDEX, found $ACTUAL."
Expand Down Expand Up @@ -337,6 +338,10 @@ jobs:
run: npm run test:happy-path -w scripts/harness
env:
HARNESS_NETWORK: local
- name: Read the share price through SEP-40 on the local network
run: npm run test:sep40 -w scripts/harness
env:
HARNESS_NETWORK: local
- name: Run the vault guards on the local network
run: npm run test:guards -w scripts/harness
env:
Expand Down
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,8 @@ contracts. The addresses emitted by the deploy script are authoritative.
and with no issue numbers or decision ids.
- **Exact pins.** Every crates.io dependency, dev-dependencies included, is
pinned with `=` to the version in `Cargo.lock`.
- **Examples.** `examples/` holds contracts that show a third party using the
kit; an example depends on no kit crate, only on standards such as `sep40`.

## Conventions

Expand Down
8 changes: 8 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[workspace]
resolver = "2"
members = ["crates/*", "contracts/*"]
members = ["crates/*", "contracts/*", "examples/*"]

[workspace.package]
edition = "2021"
Expand Down
21 changes: 21 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,27 @@ refused with `ClaimNotCovered`. It fails at simulation and leaves no
transaction, so the evidence of the short reserve is the pricing transaction
before it and the `fund` that clears it.

## SEP-40 price feed

The feed answers a vault's share price through SEP-40, the Stellar price-feed
interface, so a third-party contract can read it without depending on any kit
crate ([ADR](./docs/adr/0001-sep40-feed.md)). The harness repeats the scenario
with the team's keys: it deploys a new consumer and, when the NAV is stale,
first attests a fresh one on the oracle:

```sh
HARNESS_NETWORK=testnet npm run test:sep40 -w scripts/harness
```

| Step | Contract | Transaction |
| --- | --- | --- |
| Deploy the consumer | `sep40_consumer` `CDKCYZ6IHE2I6KAGATCQPTOYX7GUTTCYRLK26HOQ2JVHEHGXNVA27DOJ` | [`5142b57e…4505`](https://stellar.expert/explorer/testnet/tx/5142b57e6f09a07dcf7d07b09aa41818c85e9b8460165067dddc0071057a4505) |
| Attest a fresh NAV | `nav_oracle` | [`3478b5b3…2bf2`](https://stellar.expert/explorer/testnet/tx/3478b5b3a2abf4b7435832e13aca2cc2f40c0aa2228f2a4e8cf5218ecf752bf2) |
| Call `record_price` against the feed | `sep40_consumer` | [`eb0fd738…fba7`](https://stellar.expert/explorer/testnet/tx/eb0fd738e9ffa10f736946c7fb8c51f18a7595ab941214aa9f3c8a9c4beffba7) |

The call recorded a price of 1.00100000000000 (100100000000000 at 14
decimals) on 2026-11-11. The mainnet run is tracked in #433.

## Vault figures

The [live dApp](https://strata-vault-kit-app.vercel.app) shows Withdrawable and
Expand Down
6 changes: 4 additions & 2 deletions crates/strata-bindings/tests/spec_docs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@ use std::path::Path;

const SPEC_DOC_LIMIT: usize = 1024;

/// Every entrypoint and error enum of the six contracts lives in these files.
const CONTRACT_SOURCES: [&str; 8] = [
/// Every entrypoint and error enum of the six contracts, plus each example,
/// lives in these files.
const CONTRACT_SOURCES: [&str; 9] = [
"contracts/async-vault/src/lib.rs",
"contracts/async-vault/src/error.rs",
"contracts/share-token/src/contract.rs",
Expand All @@ -17,6 +18,7 @@ const CONTRACT_SOURCES: [&str; 8] = [
"contracts/compliance/src/lib.rs",
"contracts/identity-verifier/src/lib.rs",
"contracts/sep40-feed/src/lib.rs",
"examples/sep40-consumer/src/lib.rs",
];

/// The doc of every function, enum and enum variant in `source`, joined the
Expand Down
3 changes: 2 additions & 1 deletion docs/TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,7 @@ the next sealed epoch is not priced by that report. `setup_unfinished()` and
| An oracle upgraded in place cannot read a report an earlier release stored; pausing the NAV, clearing the report and lifting the pause let the attester post a new one | [`contracts/nav-oracle/src/test/oracle.rs`](../contracts/nav-oracle/src/test/oracle.rs) | `a_report_of_the_earlier_shape_is_cleared_and_replaced` |
| The SEP-40 feed reads the vault's asset, share token, wind-down state and oracle on every quote, so a failing read anywhere in that chain gives no price rather than a stale one, and it follows an oracle swap without any change of its own | [`contracts/sep40-feed/src/test/quotes.rs`](../contracts/sep40-feed/src/test/quotes.rs), [`contracts/sep40-feed/src/test/kit.rs`](../contracts/sep40-feed/src/test/kit.rs) | `a_failing_read_gives_no_price`, `the_feed_follows_an_oracle_swap`, `the_feed_quotes_a_kit_vault_through_its_oracle` |
| Proposing the feed's upgrade against a real kit vault asks that vault's governance to sign, the same as against the stubs; called directly, `upgrade` does not exist | [`contracts/sep40-feed/src/test/kit.rs`](../contracts/sep40-feed/src/test/kit.rs), [`contracts/sep40-feed/src/test/timelock.rs`](../contracts/sep40-feed/src/test/timelock.rs) (needs `upgrade_wasm`) | `an_upgrade_is_signed_by_the_kit_vaults_governance`, `the_feed_exposes_no_immediate_upgrade` |
| A third-party contract that knows only the `sep40` crate reads a quoted or missing price, an unknown asset, a feed that traps, and a feed address that is not a contract (e.g. an account), always recording exactly one of `PriceRecorded` or `NoPrice`; a feed that uses up the whole budget still fails the call. The harness repeats the quoted-price case against the deployed feed | [`examples/sep40-consumer/src/test.rs`](../examples/sep40-consumer/src/test.rs), [`scripts/harness/sep40-consumer.test.ts`](../scripts/harness/sep40-consumer.test.ts) | `a_quoted_asset_records_its_price`, `a_missing_price_records_no_price`, `an_unknown_asset_records_no_price`, `a_feed_that_fails_records_no_price`, `an_account_address_records_no_price` |

The harness's own attestations, from its tests and `npm run seed`, carry the
SHA-256 of [`docs/evidence/sample-valuation.md`](./evidence/sample-valuation.md),
Expand All @@ -205,7 +206,7 @@ without a warning. Each contract's error codes stay inside the block

| Behaviour | Tests | Key test names |
| --- | --- | --- |
| Every entrypoint and error variant doc of the six contracts fits in 1,024 bytes | [`crates/strata-bindings/tests/spec_docs.rs`](../crates/strata-bindings/tests/spec_docs.rs) | `every_contract_doc_fits_the_spec` |
| Every entrypoint and error variant doc of the six contracts, plus the SEP-40 consumer example, fits in 1,024 bytes | [`crates/strata-bindings/tests/spec_docs.rs`](../crates/strata-bindings/tests/spec_docs.rs) | `every_contract_doc_fits_the_spec` |
| An error enum declared through `error_enum!` compiles only while every code stays in its contract's block | [`crates/strata-bindings/src/errors.rs`](../crates/strata-bindings/src/errors.rs) (doctests) | the in-range example compiles; the out-of-range one fails with `E0080` |
| Every `#[only_role]` string literal matches one of its contract's role constants | [`crates/strata-bindings/tests/role_checks.rs`](../crates/strata-bindings/tests/role_checks.rs) | `every_only_role_literal_matches_its_role_constant` |

Expand Down
17 changes: 17 additions & 0 deletions examples/sep40-consumer/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
[package]
name = "sep40-consumer"
version = "0.1.0"
edition.workspace = true
license.workspace = true
publish = false

[lib]
crate-type = ["lib", "cdylib"]
doctest = false

[dependencies]
soroban-sdk = { workspace = true }
sep40 = { path = "../../crates/sep40" }

[dev-dependencies]
soroban-sdk = { workspace = true, features = ["testutils"] }
103 changes: 103 additions & 0 deletions examples/sep40-consumer/src/lib.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
//! # Design
//!
//! A third-party contract that reads a SEP-40 feed and records what it finds.
//! It proves the standard alone is enough to consume a feed; it is not part
//! of the kit.
//!
//! - **Knows only SEP-40.** It depends on the `sep40` crate alone, never on a
//! kit crate. The cost: it cannot tell a kit feed from any other SEP-40
//! feed, nor use anything the kit adds beyond the standard.
//! - **Never panics on a missing price or a failing feed.** A feed that
//! answers no price, whose call fails outright, or whose address is not a
//! contract, all end in `NoPrice`. The cost: a malformed feed address and
//! an honest "no price yet" look the same from here. A feed that uses up
//! the whole transaction budget still fails the call; this contract cannot
//! protect against that.
//! - **One event per call.** `record_price` always emits exactly one of
//! `PriceRecorded` or `NoPrice`. The cost: a caller watching only one event
//! kind must still handle the other.
//! - **No state.** Nothing is written to instance or persistent storage; the
//! price lives only in the event. The cost: no history, no last-known
//! price to read back from the contract itself.
//! - **Anyone may call it.** `record_price` takes no authorization. The cost:
//! anyone can spend the call's fee to record a price, including a stale or
//! absent one.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a bullet saying staleness checks are left to callers, so integrators don't copy it as-is?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 6079c4b: a design bullet says the consumer leaves the price's age to the caller, and what that costs if copied as is.


#![no_std]

#[cfg(test)]
mod test;

use sep40::{Asset, PriceFeedClient};
use soroban_sdk::{contract, contractevent, contractimpl, Address, Env, Executable};

#[contractevent]
pub struct PriceRecorded {
#[topic]
pub feed: Address,
#[topic]
pub asset: Asset,
pub price: i128,
pub timestamp: u64,
pub decimals: u32,
pub resolution: u32,
}

#[contractevent]
pub struct NoPrice {
#[topic]
pub feed: Address,
#[topic]
pub asset: Asset,
}

#[contract]
pub struct Sep40Consumer;

#[contractimpl]
impl Sep40Consumer {
/// Reads `feed`'s price for `asset` and records what it finds.
///
/// # Arguments
///
/// * `feed` - The SEP-40 feed to read.
/// * `asset` - The asset to price, in the feed's own terms.
///
/// # Events
///
/// * `PriceRecorded` - `feed` answered `decimals`, `resolution` and a
/// price for `asset`.
/// * `NoPrice` - Any of those reads failed, the feed named no price, or
/// `feed` is not a contract address.
///
/// # Authorization
///
/// None.
pub fn record_price(e: &Env, feed: Address, asset: Asset) {
if !matches!(feed.executable(), Some(Executable::Wasm(_))) {
NoPrice { feed, asset }.publish(e);
return;
}

let client = PriceFeedClient::new(e, &feed);
let reading = (
client.try_decimals(),
client.try_resolution(),
client.try_lastprice(&asset),
);

if let (Ok(Ok(decimals)), Ok(Ok(resolution)), Ok(Ok(Some(data)))) = reading {
PriceRecorded {
feed,
asset,
price: data.price,
timestamp: data.timestamp,
decimals,
resolution,
}
.publish(e);
} else {
NoPrice { feed, asset }.publish(e);
}
}
}
Loading
Loading