Skip to content
This repository has been archived by the owner on Aug 21, 2024. It is now read-only.

Refactor wrap/deploy of SAC #718

Merged
merged 13 commits into from
Feb 20, 2024
63 changes: 63 additions & 0 deletions docs/guides/cli/deploy-SAC.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
tupui marked this conversation as resolved.
Show resolved Hide resolved
title: Deploy a token using the Stellar Asset Contract
tupui marked this conversation as resolved.
Show resolved Hide resolved
hide_table_of_contents: true
---

The Soroban CLI can be used to deploy an existing Stellar asset into a [Stellar Asset Contract] token that can be used in Soroban smart contracts:
tupui marked this conversation as resolved.
Show resolved Hide resolved

```bash
soroban contract asset deploy \
--source S... \
--network testnet \
--asset USDC:GCYEIQEWOCTTSA72VPZ6LYIZIK4W4KNGJR72UADIXUXG45VDFRVCQTYE
```

The `asset` argument corresponds to the symbol and it's issuer address.
tupui marked this conversation as resolved.
Show resolved Hide resolved

The same can be done for the native [Lumens] asset:

```bash
soroban contract asset deploy \
--source S... \
--network testnet \
--asset native
```

:::note

Deploying the native asset will fail on testnet or mainnet as
a Soroban Asset contract already exists.

:::

For any asset, the SAC id can be fetched with:
tupui marked this conversation as resolved.
Show resolved Hide resolved

```bash
soroban contract id asset \
--source S... \
--network testnet \
--asset native
```

The SAC id can then be used in a Soroban contract as any other asset:
tupui marked this conversation as resolved.
Show resolved Hide resolved

```rust
use soroban_sdk::token;

struct MyContract;

#[contractimpl]
impl MyContract {
fn token_fn(e: Env, token_id: BytesN<32>) {
tupui marked this conversation as resolved.
Show resolved Hide resolved
// Create a client instance for the provided token identifier. If the
// `token_id` value corresponds to an SAC contract, then SAC implementation
// is used.
let client = token::Client::new(&env, &token_id);
// Call token operations.
client.transfer(...);
}
}
```

[Stellar Asset Contract]: ../../tokens/stellar-asset-contract.mdx
[Lumens]: https://developers.stellar.org/docs/fundamentals-and-concepts/lumens
25 changes: 0 additions & 25 deletions docs/guides/cli/wrap-token.mdx

This file was deleted.

9 changes: 7 additions & 2 deletions docs/tokens/stellar-asset-contract.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,19 +36,24 @@ smart contract developers to get started on Stellar.

## Deployment

For every Stellar asset exactly one respective Stellar Asset Contract can be
deployed. It can be deployed using the `InvokeHostFunctionOp` with
For every Stellar asset that already exactly on the Stellar network,
tupui marked this conversation as resolved.
Show resolved Hide resolved
one respective Stellar Asset Contract can be deployed on the Soroban platform.

It can be deployed using the `InvokeHostFunctionOp` with
`HOST_FUNCTION_TYPE_CREATE_CONTRACT` and `CONTRACT_ID_FROM_ASSET` specified
[here](../soroban-internals/contract-interactions/stellar-transaction.mdx). The resulting token will have a
deterministic identifier, which will be the sha256 hash of
`HashIDPreimage::ENVELOPE_TYPE_CONTRACT_ID_FROM_ASSET` xdr specified [here][contract_id].

Or the [Soroban-CLI] can be used as showed [here][../guides/cli/deploy-SAC.mdx].

Anyone can deploy the instances of Stellar Asset Contract. Note, that the
initialization of the Stellar Asset Contracts happens automatically during the
deployment. Asset Issuer will have the administrative permissions after the
contract has been deployed.

[contract_id]: https://github.com/stellar/stellar-xdr/blob/dc23adf60e095a6ce626b2b09128e58a5eae0cd0/Stellar-transaction.x#L661
[Soroban-CLI]: ../reference/soroban-cli.mdx

## Interacting with classic Stellar assets

Expand Down
35 changes: 1 addition & 34 deletions docs/tutorials/tokens.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -548,13 +548,12 @@ streamline token deployments, Soroban implements the [Token Interface], which
provides a uniform, predictable interface for developers and users.

Creating a Soroban token from an existing Stellar asset is very easy, and the
wrapped token makes use of the [Stellar Asset Contract] (more on that [later]).
wrapped token makes use of the [Stellar Asset Contract].
tupui marked this conversation as resolved.
Show resolved Hide resolved
This example contract, however, demonstrates how a smart contract token might be
constructed that doesn't take advantage of the Stellar Asset Contract, but does
still satisfy the commonly used Token Interface to maximize interoperability.

[Stellar Asset Contract]: ../tokens/stellar-asset-contract.mdx
[later]: #compatibility-with-stellar-assets

### Separation of Functionality

Expand Down Expand Up @@ -648,38 +647,6 @@ _require_ the right kind of behavior to take place.

:::

### Compatibility with Stellar Assets

One of the key benefits of the Stellar network is that assets are first-class
citizens. On a protocol level, asset issuers have a robust set of tools to
manage the authorization and behavior of assets. Any asset that already exists
on the Stellar network can also make use of the [Stellar Asset Contract] on the
Soroban platform. All that is required is a simple, one-time action of wrapping
the asset to be deployed for Soroban.

At that point, the asset can use all the features of the Stellar Asset Contract
that are highlighted in this example (allowance, mint, burn, etc.), while still
maintaining the high-quality asset issuer features included with Stellar.

Additionally, all of that comes with **no contract writing required**. Any asset
can be easily wrapped using the [Soroban-CLI]:

```bash
soroban lab token wrap \
--asset USDC:GCYEIQEWOCTTSA72VPZ6LYIZIK4W4KNGJR72UADIXUXG45VDFRVCQTYE
```

:::note

A Stellar asset could be wrapped for Soroban by _any_ user. This command will
set the asset issuer account as the `admin` address for the Soroban token,
meaning that issuer account will still maintain control over asset minting,
authorization, etc.

:::

[Soroban-CLI]: ../reference/soroban-cli.mdx

## Tests

Open the `token/src/test.rs` file to follow along.
Expand Down