Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

chore: Removed v2 SDK and added docs for v3 #177

Open
wants to merge 4 commits into
base: develop
Choose a base branch
from
Open

chore: Removed v2 SDK and added docs for v3 #177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fab3afa
chore: Removed `v2` SDK and added docs for `v3`
saadahmsiddiqui Oct 11, 2024
b1ee656
fix: typos
saadahmsiddiqui Nov 12, 2024
a1969a6
fix: typos
saadahmsiddiqui Nov 14, 2024
53b249f
fix: typo
saadahmsiddiqui Nov 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/03-sygma-sdk/02-Quick-Start/01-installing-the-sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,16 @@ draft: false

The SDK is written in TypeScript and can be used in both Node.js and browser environment.

To install the [@buildwithsygma/sygma-sdk-core package](https://www.npmjs.com/package/@buildwithsygma/sygma-sdk-core), you can use either npm or yarn. To install using npm, run the following command:
To install the SDK, you can use either npm or yarn. To install using npm, run the following command:

```bash
npm install @buildwithsygma/sygma-sdk-core
npm install @buildwithsygma/core @buildwithsygma/evm @buildwithsygma/substrate
```

To install using yarn, run the following command:

```bash
yarn add @buildwithsygma/sygma-sdk-core
yarn add @buildwithsygma/core @buildwithsygma/evm @buildwithsygma/substrate
```

That's it! Once you've installed the package, you can start using it in your project.
That's it! Once you've installed the package, you can start using it in your project.
108 changes: 39 additions & 69 deletions docs/03-sygma-sdk/02-Quick-Start/02-evm-token-tranfers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,92 +11,62 @@ draft: false
In the examples below `Ethers` v5 was used. If you were to use v6, keep in mind the differences between versions.
:::

### Transferring a fungible asset between EVM chains
# Transferring a fungible asset between EVM chains

Transferring assets between EVM-based chains can be achieved using the Sygma SDK.
Transferring assets between EVM-based chains can be achieved using the Sygma SDK. To facilitate the transfer, the following steps are required:

To facilitate the transfer, the following steps are required:
1. Specify transfer parameters such as amount, recipient address, token, destination chain and use the method `createFungibleAssetTransfer` from `@buildwithsygma/evm` to create an instance of `FungibleAssetTransfer`
2. Check for any approvals required, and if required sign and broadcast these transactions.
3. Prepare, sign, and send the Transfer transaction to the Source network node

1. Create an instance of the `EvmAssetTransfer` object and initialize it.
2. Determine the fee for the transfer, using the EvmAssetTransfer `getFee()` method
3. Check for any approvals required, and if required sign and broadcast these transactions.
4. Prepare, sign, and send the `Transfer` transaction to the Source network node
## 1. Create and initialize the transfer object

To initialize the asset transfer object, the following parameters are required:

#### 1. Initialize the EvmAssetTransfer object
- An `EIP-1193` compatible EVM provider
- Environment variable `SYGMA_ENV` needs to be set as `mainnet` or `testnet`

To initialize the asset transfer object, the following parameters need to be supplied:

- An instance of Ethers provider
- The environment in which the bridge should function

```ts
const assetTransfer = new EvmAssetTransfer();

const provider = new JsonRpcProvider("https://URL-TO-YOUR-RPC")

await assetTransfer.init(
provider,
Environment.TESTNET // (i.e. DEVNET, TESTNET, MAINNET)
);
```typescript
const fungibleTokenTransfer = await createFungibleAssetTransfer({
source: 1, // Ethereum Mainnet
destination: 8453, // Base
sourceNetworkProvider: eip1193CompatibleProvider,
resource:
"0x0000000000000000000000000000000000000000000000000000000000000002", // ETH Resource ID can be found here: https://github.com/sygmaprotocol/sygma-shared-configuration/blob/0e3470df4935ae3cce8b44f496723070ff3b3d1c/mainnet/shared-config-mainnet.json
amount: BigInt(1) * BigInt(1e17),
recipientAddress: "",
sourceAddress: sourceAddress, // source wallet address
});
```

#### 2. Get fee

To facilitate the transfer of tokens, a fee must be attached. This fee can be determined by utilizing the asset transfer `GetFee(transfer)` method. You will need to know the destination ChainID as well as the ResourceID that has been configured on the bridge. These details can be determined by inspecting the configurations of the bridge (see [here](https://docs.buildwithsygma.com/environments))
## 2. Send Approval transactions

```ts
const wallet = new Wallet(
privateKey as string, // use the dotenv module to pull in a private key from a .env file
provider
);
You can check if approvals are required for your transfer. If there are approvals required for the transfer, you can sign the transaction and send it.

const transfer = await assetTransfer.createFungibleTransfer(
await wallet.getAddress(),
DESTINATION_CHAINID,
DESTINATION_ADDRESS,
RESOURCE_ID,
"AMOUNT" // use appropriate decimal places based on the token and/or ecosystem you are operating in
)

const fee = await assetTransfer.getFee(transfer);
```typescript
const approvals = await fungibleTokenTransfer.getApprovalTransactions();
for (const approval of approvals) {
const tx = await wallet.sendTransaction(approval);
await tx.wait();
}
```

#### 3. Check Approvals
## 3. Send transfer transaction

You can check if approvals are required for your transfer. If there are approvals required for the transfer and the `fee` has been obtained, you can sign the transaction and send it.
Once all the approvals have been confirmed you can finally send the actual fungible token transfer transaction.

```ts
// Build approvals given the `transfer` and `fee` parameters
const approvals = await assetTransfer.buildApprovals(transfer, fee);

// Check if approvals are needed
for (const approval of approvals) {
const response = await wallet.sendTransaction(
approval as providers.TransactionRequest
);
console.log("Sent approval with hash: ", response.hash);
}

// Build the transfer transaction
const transferTx = await assetTransfer.buildTransferTransaction(
transfer,
fee
);

// Send the transaction using the wallet
const response = await wallet.sendTransaction(
transferTx as providers.TransactionRequest
);
```typescript
const transfer = await transfer.getTransferTransaction();
const tx = await wallet.sendTransaction(transfer);
await tx.wait();
```

#### Check Transaction Hash
### Checking transaction hash

The `response` object returned by the `sendTransaction` method contains a `hash` property. This transaction hash is logged to the console, and it can be used to look up the transaction on a block explorer.
The response object returned by the `sendTransaction` method contains a hash property. This transaction hash is logged to the console, and it can be used to look up the transaction on a block explorer.

```ts
// Print the transaction hash
console.log("Sent transfer with hash: ", response.hash);
```typescript
console.log("Sent transfer with hash: ", tx.hash);
```

A full example of the above can be found [here](https://github.com/sygmaprotocol/sygma-sdk/blob/main/examples/evm-to-evm-fungible-transfer/src/transfer.ts)
A full example of the above can be found [here](https://github.com/sygmaprotocol/sygma-sdk/blob/main/examples/evm-to-evm-fungible-transfer/src/transfer.ts)
96 changes: 26 additions & 70 deletions docs/03-sygma-sdk/02-Quick-Start/03-substrate-token-transfer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,85 +7,41 @@ sidebar_position: 3
draft: false
---

### Transferring a fungible asset from Substrate to EVM
# Substrate to EVM Fungible token transfer

Transferring assets from Substrate-based chains to EVM-based chains can be achieved using the Sygma SDK.
Transferring assets from Substrate-based chains to EVM-based chains can be achieved using the Sygma SDK. To facilitate the transfer, the following steps are required:

To facilitate the transfer, the following steps are required:
1. Specify transfer parameters such as amount, recipient address, token, destination chain and use the method `createSubstrateFungibleAssetTransfer` from `@buildwithsygma/substrate` to create an instance of `SubstrateFungibleAssetTransfer`
2. Sign and send the transfer transaction using `polkadot.js`

1. Create an instance of the `SubstrateAssetTransfer` object and initialize it
2. Determine the fee for the transfer, using the SubstrateAssetTransfer `getFee()` method
3. Prepare, sign, and send the `Transfer` transaction to the Substrate node

#### 1. Initialize the SubstrateAssetTransfer object
## 1. Create and initialize the transfer object

To initialize the asset transfer object, the following parameters need to be supplied:

- An instance of the PolkadotJS ApiPromise object
- The environment in which the bridge should function

```ts
const assetTransfer = new SubstrateAssetTransfer();

const wsProvider = new WsProvider("wss://URL-TO-YOUR-SUBSTRATE-INSTANCE");

// Create an instance of the PolkadotJS ApiPromise
const api = await ApiPromise.create({ provider: wsProvider });

await assetTransfer.init(
api,
Environment.TESTNET // (i.e. DEVNET, TESTNET, MAINNET)
);
```

#### 2. Get fee

To facilitate the transfer of tokens, a fee must be attached. This fee can be determined by utilizing the asset transfer `GetFee(transfer)` method. You will need to know the destination ChainID as well as the ResourceID that has been configured on the bridge. These details can be determined by inspecting the configurations of the bridge (see [here](https://docs.buildwithsygma.com/environments))


```ts

const keyring = new Keyring({ type: "sr25519" });
await cryptoWaitReady();
const account = keyring.addFromUri(MNEMONIC); // use the dotenv module to pull in a mnemonic from a .env file
const transfer = await assetTransfer.createFungibleTransfer(
account.address,
DESTINATION_CHAINID,
DESTINATION_ADDRESS,
RESOURCE_ID,
"AMOUNT" // use appropriate decimal places based on the token and/or ecosystem you are operating in
)

const fee = await assetTransfer.getFee(transfer);

- An instance of the PolkadotJS `ApiPromise` object
- Environment variable `SYGMA_ENV` needs to be set as `mainnet` or `testnet`

```typescript
const fungibleTokenTransfer = await createSubstrateFungibleAssetTransfer({
source: 5232, // Phala
destination: 1, // Ethereum Mainnet
sourceNetworkProvider: apiPromise,
sourceAddress: "<substrate_address>",
resource:
"0x0000000000000000000000000000000000000000000000000000000000000001", // PHA resource ID more resources can be found here: https://github.com/sygmaprotocol/sygma-shared-configuration/blob/main/mainnet/shared-config-mainnet.json
amount: BigInt(1) * BigInt(1e12),
destinationAddress: "<evm_recipient_address>",
});
```

#### Prepare the transfer transaction

Now that the fee has been determined, the transaction to deposit assets into the bridge should be generated, signed, and broadcast to the network.

```ts
// Build the transfer transaction
const transferTx = assetTransfer.buildTransferTransaction(
transfer,
fee
);
## 2. Sign and send transfer transaction

// Sign and broadcast the transfer transaction
const unsub = await transferTx.signAndSend(account, ({ status }) => {
console.log(`Current status is ${status.toString()}`);

if (status.isInBlock) {
console.log(
`Transaction included at blockHash ${status.asInBlock.toString()}`
);
} else if (status.isFinalized) {
console.log(
`Transaction finalized at blockHash ${status.asFinalized.toString()}`
);
unsub();
}
```typescript
const tx = await fungibleTokenTransfer.getTransferTransaction();
await transferTx.signAndSend(account, (results) => {
const { status } = results;
console.log(`Current status is ${status.toString()}`);
});
```

A full example of the above can be found [here](https://github.com/sygmaprotocol/sygma-sdk/blob/main/examples/substrate-to-evm-fungible-transfer/src/transfer.ts)
A full example of the above can be found [here](https://github.com/sygmaprotocol/sygma-sdk/blob/main/examples/substrate-to-evm-fungible-transfer/src/transfer.ts)
98 changes: 34 additions & 64 deletions docs/03-sygma-sdk/02-Quick-Start/04-gmp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,79 +11,49 @@ draft: false
In the examples below `Ethers` v5 was used. If you were to use v6, keep in mind the differences between versions.
:::

### Transferring a message between EVM chains
# Generic Message Passing (GMP)

Generic messages can be transferred between EVM chains using the Sygma SDK.
Generic messages can be transferred between EVM chains using the Sygma SDK. To facilitate the transfer, the following steps are required:

To facilitate the transfer, the following steps are required:
1. Specify generic message transfer parameters and create an instance of `GenericMessageTransfer` using `createCrossChainContractCall` method from `@buildwithsygma/evm` package.
2. Sign and send the transfer transaction.

1. Create an instance of the `EVMGenericMessageTransfer` object and initialize it.
2. Determine the fee for the transfer, using the `EVMGenericMessageTransfer.getFee()` method
3. Prepare, sign, and send the Transfer transaction to the Source network node
There are a few requirements for the Destination chain contract function that gets called. Refer to the [Generic Message Passing documentation](../../02-sygma-protocol/06-generic.md) for details.

The `executeDeposit` function prepares and populates a deposit transaction. The key parameter is `depositData`, which is a string requiring a specific format. Refer to the [Generic Message Passing](../../02-sygma-protocol/06-generic.md) documentation for instructions on how to format the `depositData` string correctly.

There are a few requirements for the Destination chain contract function that gets called. Refer to the [Generic Message Passing](../../02-sygma-protocol/06-generic.md) documentation for details.

#### 1. Initialize the EvmAssetTransfer object
## 1. Create and initialize the transfer object

To initialize the generic message transfer object, the following parameters need to be supplied:

- An instance of Ethers provider
- The environment in which the bridge should function

```ts
const messageTransfer = new EVMGenericMessageTransfer();

const sourceProvider = new providers.JsonRpcProvider(
"https://URL-TO-YOUR-RPC"
);
const destinationProvider = new providers.JsonRpcProvider(
"https://URL-TO-YOUR-RPC"
);

await messageTransfer.init(
sourceProvider,
Environment.TESTNET // (i.e. DEVNET, TESTNET, MAINNET)
);
```

#### 2. Get fee

To facilitate the transfer of a generic message, a fee must be paid. This fee can be determined by utilizing the `messageTransfer.getFee(transfer)` method. You will need to know the destination ChainID as well as the ResourceID that has been configured on the bridge. These details can be determined by inspecting the configurations of the bridge (see [here](https://docs.buildwithsygma.com/environments))


```ts
const wallet = new Wallet(
privateKey ?? "", // use the dotenv module to pull in a private key from a .env file
sourceProvider
);

const transfer = messageTransfer.createGenericMessageTransfer(
await wallet.getAddress(),
DESTINATION_CHAINID,
RESOURCE_ID,
DESTINATION_CONTRACT_ADDRESS, // contract address you are calling to
DESTINATION_FUNCTION_SIGNATURE, // function signature you are invoking cross-chain
EXECUTION_DATA, // the actual data payload that the smart contract function is expecting
MAX_FEE
)

const fee = await messageTransfer.getFee(transfer);
- An `EIP-1193` compatible EVM provider
- Environment variable `SYGMA_ENV` needs to be set as `mainnet` or `testnet`
- Address, `ABI` of the contract and the function that will be invoked on the destination chain.

```typescript
const gmpTransfer = await createCrossChainContractCall<
typeof sepoliaBaseStorageContract,
"store"
>({
gasLimit: BigInt(0),
functionParameters: ["0x<addr1>", "0x<addr2>", BigInt(1)],
functionName: "store",
destinationContractAbi: sepoliaBaseStorageContract,
destinationContractAddress: "0x4bE595ab5A070663B314970Fc10C049BBA0ad489",
maxFee: BigInt("3000000"),
source: 11155111, // Sepolia
destination: 84532, // Base Sepolia
sourceNetworkProvider: eip1193CompatibleProvider,
sourceAddress: "<source_evm_wallet_address>",
resource:
"0x0000000000000000000000000000000000000000000000000000000000000600",
});
```
### 3. Prepare, sign, and send the Transfer transaction to the Source network node

```ts
const transferTx = await messageTransfer.buildTransferTransaction(
transfer,
fee
);
## 2. Sign and send the transfer transaction

// Send the transaction using the wallet
const response = await wallet.sendTransaction(
transferTx as providers.TransactionRequest
);
console.log("Sent transfer with hash: ", response.hash);
```typescript
const transaction = await gmpTransfer.getTransferTransaction();
const tx = await wallet.sendTransaction(transaction);
await tx.wait();
```

A full example of the above can be found [here](https://github.com/sygmaprotocol/sygma-sdk/blob/main/examples/evm-to-evm-generic-mesage-passing/src/transfer.ts)
A full example of the above can be found [here](https://github.com/sygmaprotocol/sygma-sdk/blob/main/examples/evm-to-evm-generic-message-transfer/src/transfer.ts)
Loading
Loading