Skip to content

Instantly share code, notes, and snippets.

@Shaptic

Shaptic/protocol-20-sdk.md

Last active September 19, 2023 18:22
Show Gist options
  • Save Shaptic/a82fff91ef91955feb3b49af8a7c24b1 to your computer and use it in GitHub Desktop.
Save Shaptic/a82fff91ef91955feb3b49af8a7c24b1 to your computer and use it in GitHub Desktop.
Download ZIP
Support for Protocol 20: Soroban
Raw
protocol-20-sdk.md

When closing this issue, please respond with at least the GitHub release that supports Protocol 20.

Protocol 20: Soroban

The next version of the Stellar network will feature a new smart contract platform called Soroban. Note that this version features only additive changes: existing operations, etc. have not changed. (Protocol 20 will be the same thing as "Preview 11," the latest release of Soroban to Stellar Futurenet.)

New XDR Schema

  • Your SDK should support encoding and decoding the new XDR schemas. The network protocol will use the XDR schema defined here: stellar-xdr @ 9ac0264.
  • There are three new operations. The former is for invoking contract actions, while the latter two are related to state expiration (see Interacting with Soroban via Stellar and State Expiration):
    • invokeHostFunctionOp takes a function to invoke (e.g. contract creation, uploads, method invocation) and the corresponding authorization to perform that action (JS reference: )
    • bumpExpirationFootprintOp, which takes a ledgersToExpire and bumps the expiration ledger of the ledger keys specified in the transaction
    • restoreFootprintOp restores the expiration of the ledger keys specified in the transaction
    • Notice that the latter two have no parameters to describe what ledger entries are bumping or restoring. This is because they reference the transaction-level Soroban data access pattern, which is a bit of a paradigm shift of the "all-inclusive" operations we've seen before.
  • Ideally, it should also provide abstractions for various high-profile components of building Soroban applications. You can use the JavaScript SDKs for references, though these are likely not idiomatic, and may change in the near future as use-cases are better understood. These are in relative order of priority:

You may also want to look into how the TypeScript bindings are generated (code link) via the new soroban command line tool and add a generator for your particular language.

New client libary: Soroban RPC

Horizon API

The following APIs have changed:

  • /effects can produce two new effects:
    • contract_credited occurs when a Stellar asset moves into its corresponding Stellar Asset Contract instance
    • contract_debited occurs when a Stellar asset moves out of its corresponding Stellar Asset Contract instance
  • /assets/:name contains two new fields:
    • num_contracts - the integer quantity of contracts that hold this asset
    • contracts_amount - the total units of that asset held by contracts
  • /operations has three new response schemas corresponding to the Soroban operations (described above):
// when type: 'invokeHostFunction'
{
    function: string;
    parameters: { value: string, type: string }[];
    address: string;
    salt: string;
    asset_balance_changes: {
        asset_type: string;
        asset_code?: string;
        asset_issuer?: string;

        type: string;
        from: string;
        to: string;
        amount: string;
    }[];
}
// when type: 'bumpFootprintExpiration':
{
    ledgers_to_expire: number;
}
// when type: 'restoreFootprint':
{
    // empty
}

SDF Reference Implementations

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment