Potential first oracle on Miden (DRAFT)

[Dominik1999]

An Oracle on Miden

Miden is supposed to be home to innovative DeFi solutions. Most DeFi solutions need price Oracles to query prices from other chains. For example, Perp Markets need frequent updates on the prices of the underlying assets.

Simple design

We hope to host many different Oracles in the future. A semi-mocked oracle will suffice for the current testnet. So, the design will be rather simple, but it should still serve as a PoC to see if the protocol can already support an oracle.

The Oracle account

A public account will serve as the Oracle account. In its storage, the asset prices will be stored. As long as there are not more than 254 different assets, we can use storage slots for simplicity. Later, storage maps can be used. Every storage slot can store a Word.

Prices and assets can be encoded as Word in many ways, e.g., (Base Asset / code Asset, price, publisher Id / decimals, timestamp). Every asset can have a certain ID, we can denominate the prices in $ or BTC, and the block height describes how old the information is.

Miden operator pushes new prices

For now, we want a trusted Oracle source. The Miden operator will push new price updates at certain intervals. We need to figure our how exactly this will work.

Miden users can read account state

Once #847 is fully implemented, any Miden account can read the Oracle storage during transaction execution.

Open questions

• How does the operator update the Oracle? Should it be a note that the account consumes?
• In which intervals?
• Where does the operator get the prices from?
• Should the Oracle send Notes to subscribers or should any account be able to read the storage?
• ...

[bobbinth]

Looks great! A few comments:

Prices and assets can be encoded as Word in many ways, e.g., (Base Asset / code Asset, price, publisher Id / decimals, timestamp). Every asset can have a certain ID, we can denominate the prices in $ or BTC, and the block height describes how old the information is.

It is not clear to me if we need the timestamp in there as the "readers" of the oracle will always be forced to read the most recent value.

How does the operator update the Oracle? Should it be a note that the account consumes?

I think for now this can be done by directly executing a transaction against the oracle. And also, it doesn't really have to be the operator to make these updates. In fact, it might be better is an oracle is owned by some 3rd party service which periodically submits a transaction to update the oracle.

In which intervals?

I think something between 5 - 10 blocks between updates should be OK - though, I'd probably keep it to 10 blocks to be on the safe side. In the future, we can investigate lowering this to potentially as little as 3 blocks.

Should the Oracle send Notes to subscribers or should any account be able to read the storage?

I think anyone should be able to read the oracle directly using foreign procedure invocation (e.g., no need to send notes). For example, an oracle account could expose a procedure get_btc_price which would return the most recent BTC price (procedures could be more generic as well). Then this procedure could be invoked either by account code, note script, or transaction script.

One key consideration for this procedure is how it will set transaction recency condition. For example, if the oracle is updated every 10 blocks, we may want to make sure that get_btc_price sets transaction recency to 10 blocks as well.

It may also be possible to implement "whitelists" for oracles - e.g., we can limit which accounts can call get_btc_price. Though, such designs require more consideration and I would not include them in the PoC.

[EvolveArt]

hey @bobbinth

It is not clear to me if we need the timestamp in there as the "readers" of the oracle will always be forced to read the most recent value.

The timestamp can then be used by readers to perform some checks on the freshness of the data they are reading.

I think for now this can be done by directly executing a transaction against the oracle. And also, it doesn't really have to be the operator to make these updates. In fact, it might be better is an oracle is owned by some 3rd party service which periodically submits a transaction to update the oracle.

That's exactly how we do on our V1 on starknet and I think it's a better idea so we can leverage all of our existing infra and SDK.

I think something between 5 - 10 blocks between updates should be OK - though, I'd probably keep it to 10 blocks to be on the safe side. In the future, we can investigate lowering this to potentially as little as 3 blocks.

As it's handled by a 3rd party (us) anyway this can be configured and changed easily.

Also quick Q: what are the current computational limits of Miden, i.e in one block how much computation can actually be performed.

It may also be possible to implement "whitelists" for oracles - e.g., we can limit which accounts can call get_btc_price. Though, such designs require more consideration and I would not include them in the PoC.

I dont see any advantages with this tho what would be the reason ?

[bobbinth]

It is not clear to me if we need the timestamp in there as the "readers" of the oracle will always be forced to read the most recent value.

The timestamp can then be used by readers to perform some checks on the freshness of the data they are reading.

Makes sense! One potential alternative could be to use the block height of the last update. This may be a bit more "robust".

Also quick Q: what are the current computational limits of Miden, i.e in one block how much computation can actually be performed.

This will depend on the type of transactions:

• For transactions executed and proven locally, there are no real computational limits. Basically, a transaction is limited by the user's hardware. For example, on a MacBook Pro, we should be able to do 1M cycles in about 30 seconds. On a 64-core Gravition4, the same can be done in about 10 seconds. We'll be improving performance and also adding other ways to accelerate this (e.g., via CUDA) shortly.
• The other option is what we call "network transactions" - i.e., when the network executes a transaction by itself. These are not implemented yet, but when we do implement them, we'll place a limit to be roughly something that can be executed proven in under 1 second.

It may also be possible to implement "whitelists" for oracles - e.g., we can limit which accounts can call get_btc_price. Though, such designs require more consideration and I would not include them in the PoC.

I dont see any advantages with this tho what would be the reason ?

One potential reason could be to collect payments from those who want to use the oracle. For example, an app may need to "purchase" oracle access for some duration and that would put it into the "whiltelist". But apps that didn't purchase access would not be able to read the oracle.

[Dominik1999]

Here are a couple of hints, how you can build the oracle and execute it. You can follow how a faucet is being created and executed.

Oracle account code:

The Oracle account can expose at minimum two functions, push_oracle_data and read_oracle_data. At account creation, at storage slot 0, the public key of the data provider should be stored. You can follow this account setup

miden-base/miden-tx/tests/integration/scripts/faucet.rs

Lines 234 to 252 in 6f54100

	fn get_faucet_account_with_max_supply_and_total_issuance(
	public_key: Word,
	max_supply: u64,
	total_issuance: Option<u64>,
	) -> Account {
	let faucet_account_id = AccountId::try_from(ACCOUNT_ID_FUNGIBLE_FAUCET_OFF_CHAIN).unwrap();
	let assembler = TransactionKernel::assembler();
	let faucet_account_code = AccountCode::compile(FUNGIBLE_FAUCET_SOURCE, assembler).unwrap();
	let faucet_storage_slot_1 = [Felt::new(max_supply), Felt::new(0), Felt::new(0), Felt::new(0)];
	let mut faucet_account_storage = AccountStorage::new(
	vec![
	SlotItem::new_value(0, 0, public_key),
	SlotItem::new_value(1, 0, faucet_storage_slot_1),
	],
	BTreeMap::new(),
	)
	.unwrap();

.

As for the account code, here is a simple example. You need to use the account procedures set_item and get_item from miden-lib. You can see the signatures here. This example code only allows you to store four price updates in the slots 1,2,3,4 (slot 0 is already taken for the public_key).

The "real" contract would look a bit more complex, but this could be a good start to see how things work.

const ORACLE_SOURCE: &str = "

#! Add imports
use.miden::account
use.miden::contracts::auth::basic

#! Pushes new price data into the oracle's data slots. 
#!
#! Inputs:  [WORD_1, WORD_2, WORD_3, WORD_4]
#! Outputs: [ ]
#!
#! - WORD_X is the tuple (base asset/code asset, price, decimals, publisher Id)
#!
#! Here 16 elements from the stack will be read, so we can start with 4 price updates
#! This is just to start; in the future, the inputs to this function should be (how_many_words_to_set, WORD1, WORD2, ...) 
export.push_oracle_data

   push. 1 dup movdn.5
   # => [1, WORD_1, 1, WORD_2, ...]
   
   repeat.4
        exec.account::set_item
        drow drow
        # => [index, WORD_index+1, ...]
        
        add.1 dup movdn.5
        # => [index+1, WORD_index+1, index+1, ...]
    end
end

#! Read price data from the oracle's data slots. 
#!
#! Inputs:  [base asset/code asset]
#! Outputs: [WORD]
#!
#! - WORD is the tuple (base asset/code asset, price, decimals, publisher Id)
#!
export.read_oracle_data
        exec.account::get_item
        # => [WORD]
        
        # maybe you need to bump up the nonce, not 100% sure how foreign procedure invocation works yet.
end

export.basic::auth_tx_rpo_falcon512
";

Pushing data to the oracle:

I would follow the integration test for minting tokens on a faucet, see

miden-base/miden-tx/tests/integration/scripts/faucet.rs

Lines 33 to 107 in 6f54100

	fn prove_faucet_contract_mint_fungible_asset_succeeds() {
	let (faucet_pub_key, falcon_auth) = get_new_pk_and_authenticator();
	let faucet_account =
	get_faucet_account_with_max_supply_and_total_issuance(faucet_pub_key, 200, None);
	// CONSTRUCT AND EXECUTE TX (Success)
	// --------------------------------------------------------------------------------------------
	let tx_context = TransactionContextBuilder::new(faucet_account.clone()).build();
	let executor = TransactionExecutor::new(tx_context.clone(), Some(falcon_auth.clone()));
	let block_ref = tx_context.tx_inputs().block_header().block_num();
	let note_ids = tx_context
	.tx_inputs()
	.input_notes()
	.iter()
	.map(|note| note.id())
	.collect::<Vec<_>>();
	let recipient = [Felt::new(0), Felt::new(1), Felt::new(2), Felt::new(3)];
	let tag = NoteTag::for_local_use_case(0, 0).unwrap();
	let aux = Felt::new(27);
	let note_execution_hint = NoteExecutionHint::on_block_slot(5, 6, 7);
	let note_type = NoteType::Private;
	let amount = Felt::new(100);
	assert_eq!(tag.validate(note_type), Ok(tag));
	let tx_script_code = format!(
	"
	begin
	push.{recipient}
	push.{note_execution_hint}
	push.{note_type}
	push.{aux}
	push.{tag}
	push.{amount}
	call.::miden::contracts::faucets::basic_fungible::distribute
	call.::miden::contracts::auth::basic::auth_tx_rpo_falcon512
	dropw dropw drop
	end
	",
	note_type = note_type as u8,
	recipient = prepare_word(&recipient),
	aux = aux,
	tag = u32::from(tag),
	note_execution_hint = Felt::from(note_execution_hint)
	);
	let tx_args = build_tx_args_from_script(&tx_script_code);
	let executed_transaction = executor
	.execute_transaction(faucet_account.id(), block_ref, &note_ids, tx_args)
	.unwrap();
	assert!(prove_and_verify_transaction(executed_transaction.clone()).is_ok());
	let fungible_asset: Asset =
	FungibleAsset::new(faucet_account.id(), amount.into()).unwrap().into();
	let output_note = executed_transaction.output_notes().get_note(0).clone();
	let assets = NoteAssets::new(vec![fungible_asset]).unwrap();
	let id = NoteId::new(recipient.into(), assets.commitment());
	assert_eq!(output_note.id(), id);
	assert_eq!(
	output_note.metadata(),
	&NoteMetadata::new(faucet_account.id(), NoteType::Private, tag, note_execution_hint, aux)
	.unwrap()
	);
	}

.

The data provider can use a transaction script to push the data. It would look like this

    let tx_script_code = format!(
        "
            begin

                # Load data to the stack
                push.{price_data_asset_1}
                push.{price_data_asset_2}
                ...
                push.{price_data_asset_x}
                
                # Call the oracle contract procedure
                call.push_oracle_data
                
                # Clear the stack
                dropw dropw dropw dropw

                # Sign the transaction to ensure only the data provider can push
                call.::miden::contracts::auth::basic::auth_tx_rpo_falcon512
                dropw dropw drop

            end

whereas price_data_asset_1 is the tuple (base asset/code asset, price, decimals, publisher Id).

Reading data from the oracle:

In a transaction, any account can read a certain storage slit using foreign procedure invocation. The final format will be defined next week.