Support for Protocol 20: Soroban

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:
  • a way to add xdr.SorobanTransactionData to a transaction when building it, which is a data structure that describes the resource usage of a Soroban transaction (see Transaction resources), including its storage access footprint, memory usage, etc. (JS reference: SorobanDataBuilder)
  • support for contract addresses in StrKey format (see SEP-23; JS reference: StrKey.encodeContract)
  • a way to represent contract objects and convert them to addresses (see Contract-specific Authorization, which demonstrates that an address can either be an account ID [G...] or a contract ID [C...]; JS reference: Contract and Address)
  • conversion to and from language-native values to the smart contract values (xdr.ScVal) used by Soroban (see Primitive Types; JS reference: scValToNative, scValToBigInt, nativeToScVal, and ContractSpec)
  • abstractions to perform multi-party authentication of contract invocations (see Authorization; JS reference: authorizeInvocation and authorizeEntry)

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

• Unlike Horizon, Soroban RPC uses JSON-RPC as its transport mechanism
• The methods are all documented here: https://soroban.stellar.org/api/methods
• You can use https://rpc-futurenet.stellar.org/ for testing or connect to the network with your own instance (see the RPC docs)

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

• JavaScript: low-level XDR structures, RPC API, Horizon API (note that there is no requirement to split out the APIs in this way: it's a case-by-case language/design choice)
• Golang
• Java
• Python