14 releases
0.6.15 | Sep 30, 2024 |
---|---|
0.6.13 | Jul 20, 2024 |
0.6.7 | Mar 22, 2024 |
0.6.5 | Sep 22, 2023 |
#1 in #loam
41 downloads per month
Used in 6 crates
14KB
118 lines
loam-sdk
Build composable, upgradeable, secure Smart Contracts.
-
Composable: With Loam SDK, you compose your smart contract from many sub contracts. Subcontracts are like lego blocks that you can either use off-the-shelf from the open source ecosystem or that you can build yourself. A single Loam smart contract is composed of one or more subcontracts.
-
Upgradeable: The one subcontract that all Loam smart contracts must include (loam-subcontract-core) adds an important method to the smart contract:
redeploy
. You can call this method to switch thewasm
hash—the behavior/brains of the contract—to a new one, while keeping the same contract ID. The storage accessed by each particular subcontract is loaded lazily, so upgrading one subcontract does not require migrating the data of another; each subcontract within your smart contract can be considered and upgraded independently. -
Secure: The core subcontract also adds
admin_set
andadmin_get
to your contract, to make sure that only your trusted admin account can callredeploy
. Our full loam architecture, beyond Loam SDK, also includes a universal factory contract, which makes it possible to deploy your contract and calladmin_set
in a single transaction, helping avoid front-running.
Subcontracts
A subcontract is a type that implements the IntoKey
trait, which is used for lazily loading and storing the type.
Creating Subcontracts
Here's an example of how to create a subcontract:
#[contracttype]
#[derive(IntoKey)]
pub struct Messages(Map<Address, String>);
This generates the following implementation:
impl IntoKey for Messages {
type Key = IntoVal<Env, RawVal>;
fn into_key() -> Self::Key {
String::from_slice("messages")
}
External API
You can also create and implement external APIs for contract subcontracts:
#[subcontract]
pub trait IsPostable {
fn messages_get(&self, author: Address) -> Option<String>;
fn messages_set(&mut self, author: Address, text: String);
}
Core Subcontract
The Core
trait provides the minimum logic needed for a contract to be redeployable. A contract should be able to be redeployed to another contract that can also be redeployed. Redeployment requires admin status, as it would be undesirable for an account to redeploy the contract without permission.
Using Core
To use the core subcontract, create a Contract
struct and implement Core
with the Admin
implementation, which ensures the contract is redeployable and will continue to be redeployable if the new contract also implements Core
. After Core
other Subcontracts can be added as needed.
use loam_sdk::derive_contract;
use loam_subcontract_core::{Admin, Core};
#[derive_contract(Core(Admin))]
pub struct Contract;
This code generates the following implementation:
struct SorobanContract;
#[contractimpl]
impl SorobanContract {
pub fn admin_set(env: Env, admin: Address) {
set_env(env);
Contract::owner_set(owner);
}
pub fn admin_get(env: Env) -> Option<Address> {
set_env(env);
Contract::admin_get()
}
pub fn redeploy(env: Env, wasm_hash: BytesN<32>) {
set_env(env);
Contract::redeploy(wasm_hash);
}
// Subcontract methods would be inserted here.
// Contract must implement all Subcontracts and is the proxy for the contract calls.
// This is because the Subcontracts have default implementations which call the associated type
}
By specifying the associated a concrete implementation for Core
, Admin
, you enable its methods to be used (admin_set
, admin_get
, redeploy
). However, you can also provide a different implementation if needed by replacing Admin
with a different struct/enum that also implements IsCore.
Notice that the generated code includes Contract::redeploy
and other methods. This ensures that the Contract
type is redeployable, while also allowing for extensions, as different concrete implementation can overwrite the default methods.
Dependencies
~15–24MB
~406K SLoC