Add API reference and examples page

aptos-labs · Sep 27, 2024 · 47b27ee · 47b27ee
1 parent 56e5a42
commit 47b27ee
Show file tree

Hide file tree

Showing 8 changed files with 354 additions and 0 deletions.
diff --git a/apps/nextra/pages/en/build/sdks/dotnet-sdk.mdx b/apps/nextra/pages/en/build/sdks/dotnet-sdk.mdx
@@ -83,4 +83,15 @@ Begin using the Aptos .NET SDK in your game engine of choice.
       </Card.Description>
     </div>
   </Card>
+  <Card
+    href="https://aptos-labs.github.io/aptos-dotnet-sdk/"
+    className="col-span-2 flex flex-row gap-4"
+  >
+    <div className="flex flex-col gap-2">
+      <Card.Title>Full API Reference</Card.Title>
+      <Card.Description>
+        The full API reference for the Aptos .NET SDK.
+      </Card.Description>
+    </div>
+  </Card>
 </Cards>
diff --git a/apps/nextra/pages/en/build/sdks/dotnet-sdk/_meta.tsx b/apps/nextra/pages/en/build/sdks/dotnet-sdk/_meta.tsx
@@ -14,4 +14,7 @@ export default {
   transactions: {
     title: "Transactions",
   },
+  "dotnet-examples": {
+    title: "Examples",
+  },
 };
diff --git a/apps/nextra/pages/en/build/sdks/dotnet-sdk/accounts/_meta.tsx b/apps/nextra/pages/en/build/sdks/dotnet-sdk/accounts/_meta.tsx
@@ -2,4 +2,10 @@ export default {
   ed25519: {
     title: "Ed25519 Accounts",
   },
+  keyless: {
+    title: "Keyless Accounts",
+  },
+  multikey: {
+    title: "Multikey Accounts",
+  },
 };
diff --git a/apps/nextra/pages/en/build/sdks/dotnet-sdk/accounts/ed25519.mdx b/apps/nextra/pages/en/build/sdks/dotnet-sdk/accounts/ed25519.mdx
@@ -50,3 +50,20 @@ To create a random account, you can use the `Account.Generate()` method.
 ```csharp
 var account = Account.Generate();
 ```
+
+## Additional Resources
+
+<Cards className="xl:grid-cols-2">
+  <Card
+    href="https://aptos-labs.github.io/aptos-dotnet-sdk/docs/Aptos.Ed25519Account.html"
+    className="col-span-2 flex flex-row gap-4"
+  >
+    <Card.Image src="https://cdn-icons-png.flaticon.com/512/25/25231.png" />
+    <div className="flex flex-col gap-2">
+      <Card.Title>Ed25519Account Reference</Card.Title>
+      <Card.Description>
+        The full API reference for the Ed25519Account class.
+      </Card.Description>
+    </div>
+  </Card>
+</Cards>
diff --git a/apps/nextra/pages/en/build/sdks/dotnet-sdk/accounts/keyless.mdx b/apps/nextra/pages/en/build/sdks/dotnet-sdk/accounts/keyless.mdx
@@ -0,0 +1,106 @@
+---
+title: "Keyless Accounts"
+---
+
+import { Steps, Callout } from "nextra/components";
+import { Card, Cards } from "@components/index";
+
+<Callout type="warning" emoji="❗">
+  This SDK is currently in beta. Please report any issues you encounter by
+  creating an issue in the
+  [aptos-labs/aptos-dotnet-sdk](https://github.com/aptos-labs/aptos-dotnet-sdk)
+  repository.
+</Callout>
+
+# Keyless Accounts
+
+The Aptos .NET SDK provides an implementation of Keyless accounts to derive accounts from social provider logins. In this guide,
+we will provide snippets of creating accounts.
+
+## Creating KeylessAccounts
+
+KeylessAccounts are created to sign transactions and interact with the blockchain using social provider logins. To create a Keyless account,
+you will need to follow a few steps to obtain the necessary components of a Keyless account.
+
+<Callout type="info" emoji="ℹ️">
+  We plan on creating end-to-end guides on integrating Keyless with Unity and
+  Godot. They are currently in development.
+</Callout>
+
+<Steps>
+
+### Create a Ephemeral Key Pair
+
+The first step to creating a Keyless account is to create an ephemeral key pair. This is an ephemeral key used to sign transactions. It's important
+to store this key pair in a secure location in the application as it will be used to sign transactions.
+
+```csharp
+var ephemeralKeyPair = EphemeralKeyPair.Generate();
+```
+
+### Obtaining an OpenID Connect (OIDC) Identity Token
+
+To obtain an `id_token` (OIDC Identity Token), you will need to authenticate with a social provider. At the end of the authorization flow, the user should be redirected
+to your application with an `id_token`. You will need to store this `id_token` in a secure location in the application. **It's important that the `id_token` has a nonce field that matches the `nonce` field inside the `EphemeralKeyPair`.**
+
+**Example:**
+
+```csharp
+var nonce = ephemeralKeyPair.Nonce;
+var authorizationUrl = "https://accounts.google.com/o/oauth2/v2/auth&nonce=" + nonce;
+```
+
+### Deriving a Keyless Account
+
+Once the user has the following components, they should be able to derive a Keyless account.
+
+- `id_token`: Obtained from the authorization flow.
+- `EphemeralKeyPair`: Created in the previous steps.
+
+**It's important that the `nonce` field inside the `EphemeralKeyPair` matches the `nonce` field inside the `id_token` to ensure that the user can sign transactions.**
+
+```csharp
+var client = new AptosClient(Networks.Mainnet);
+var keylessAccount = await client.Keyless.DeriveAccount(idToken, ephemeralKeyPair);
+```
+
+### Sign and Submit transactions
+
+After deriving a Keyless account, you can sign and submit transactions using the `AptosClient`.
+
+```csharp
+// 1. Build the transaction
+var transaction = await client.Transaction.Build(
+    sender: keylessAccount,
+    data: new GenerateEntryFunctionPayloadData(
+        function: "0x1::aptos_account::transfer_coins",
+        typeArguments: ["0x1::aptos_coin::AptosCoin"],
+        functionArguments: [account.Address, "100000"]
+    )
+);
+
+// 2. Sign and submit the transaction
+var submittedTransaction = await client.Transaction.SignAndSubmitTransaction(keylessAccount, transaction);
+
+// 3. (Optional) Wait for the transaction to be committed
+var committedTransaction = await client.Transaction.WaitForTransaction(submittedTransaction.Hash);
+```
+
+</Steps>
+
+## Additional Resources
+
+<Cards className="xl:grid-cols-2">
+  <Card
+    href="https://aptos-labs.github.io/aptos-dotnet-sdk/docs/Aptos.KeylessAccount.html"
+    className="col-span-2 flex flex-row gap-4"
+  >
+    <Card.Image src="https://cdn-icons-png.flaticon.com/512/25/25231.png" />
+    <div className="flex flex-col gap-2">
+      <Card.Title>KeylessAccount Reference</Card.Title>
+      <Card.Description>
+        The full API reference for the KeylessAccount class.
+      </Card.Description>
+    </div>
+  </Card>
+</Cards>
diff --git a/apps/nextra/pages/en/build/sdks/dotnet-sdk/accounts/multikey.mdx b/apps/nextra/pages/en/build/sdks/dotnet-sdk/accounts/multikey.mdx
@@ -0,0 +1,105 @@
+---
+title: "Multikey Accounts"
+---
+
+import { Steps, Callout } from "nextra/components";
+import { Card, Cards } from "@components/index";
+
+<Callout type="warning" emoji="❗">
+  This SDK is currently in beta. Please report any issues you encounter by
+  creating an issue in the
+  [aptos-labs/aptos-dotnet-sdk](https://github.com/aptos-labs/aptos-dotnet-sdk)
+  repository.
+</Callout>
+
+# Multikey Accounts
+
+The Aptos .NET SDK provides an implementation of Multikey accounts to create accounts from a combination of multiple key pairs. This is useful for
+Multisig accounts. In this guide, we will provide snippets of creating accounts.
+
+## Creating a MultiKeyAccount
+
+MultiKeyAccount's are created to sign transactions where the account is controlled by multiple private keys.
+
+### Create a MultiKeyAccount
+
+To create a MultiKey account, you will need the following components:
+
+- `PublicKeys`: The public keys of the accounts that control the MultiKey account.
+- `SignaturesRequired`: The minimum number of signers required to sign transactions.
+- `Signers`: The account signers that will be used to sign transactions. The number of signers should be equal to or greater than the `SignaturesRequired`.
+
+<Steps>
+
+### Create your Accounts
+
+Create your accounts, they can be different types of accounts.
+
+```csharp
+var account1 = Ed25519Account.Generate();
+var account2 = SingleKeyAccount.Generate(PublicKeyVariant.Secp256k1Ecdsa);
+```
+
+### Create a MultiKey Verifying Key
+
+Create a MultiKey verifying key using the `PublicKeys` and `SignaturesRequired`. In this example,
+we have two accounts controlling the MultiKey and we require 2 signers to sign transactions.
+
+```csharp
+var multiKey = new MultiKey(
+    publicKeys: [account1.PublicKey, account2.PublicKey],
+    signaturesRequired: 2,
+);
+```
+
+### Create the MultiKey Account
+
+Create the MultiKey account using the `PublicKeys`, `SignaturesRequired`, and `Signers`.
+
+```csharp
+var multikeyAccount = new MultiKeyAccount(
+    multiKey: multiKey,
+    signers: [account1, account2]
+);
+```
+
+### Sign and Submit transactions
+
+After creating a MultiKey account, you can sign and submit transactions using the `AptosClient`.
+
+```csharp
+// 1. Build the transaction
+var transaction = await client.Transaction.Build(
+    sender: multikeyAccount,
+    data: new GenerateEntryFunctionPayloadData(
+        function: "0x1::aptos_account::transfer_coins",
+        typeArguments: ["0x1::aptos_coin::AptosCoin"],
+        functionArguments: [account.Address, "100000"]
+    )
+);
+
+// 2. Sign and submit the transaction
+var submittedTransaction = await client.Transaction.SignAndSubmitTransaction(multikeyAccount, transaction);
+
+// 3. (Optional) Wait for the transaction to be committed
+var committedTransaction = await client.Transaction.WaitForTransaction(submittedTransaction.Hash);
+```
+
+</Steps>
+
+## Additional Resources
+
+<Cards className="xl:grid-cols-2">
+  <Card
+    href="https://aptos-labs.github.io/aptos-dotnet-sdk/docs/Aptos.MultiKeyAccount.html"
+    className="col-span-2 flex flex-row gap-4"
+  >
+    <Card.Image src="https://cdn-icons-png.flaticon.com/512/25/25231.png" />
+    <div className="flex flex-col gap-2">
+      <Card.Title>MultiKeyAccount Reference</Card.Title>
+      <Card.Description>
+        The full API reference for the MultiKeyAccount class.
+      </Card.Description>
+    </div>
+  </Card>
+</Cards>
diff --git a/apps/nextra/pages/en/build/sdks/dotnet-sdk/dotnet-examples.mdx b/apps/nextra/pages/en/build/sdks/dotnet-sdk/dotnet-examples.mdx
@@ -0,0 +1,89 @@
+---
+title: "Examples"
+---
+
+import { Steps, Callout } from "nextra/components";
+import { Card, Cards } from "@components/index";
+
+<Callout type="warning" emoji="❗">
+  This SDK is currently in beta. Please report any issues you encounter by
+  creating an issue in the
+  [aptos-labs/aptos-dotnet-sdk](https://github.com/aptos-labs/aptos-dotnet-sdk)
+  repository.
+</Callout>
+
+# Examples
+
+The Aptos .NET SDK provides a number of examples to help you get started with the SDK. You can find the examples in the
+[aptos-labs/aptos-dotnet-sdk](https://github.com/aptos-labs/aptos-dotnet-sdk) repository.
+
+<br />
+
+<Card
+  href="https://github.com/aptos-labs/aptos-dotnet-sdk/tree/main/Aptos.Examples"
+  className="flex flex-row gap-4"
+>
+  <Card.Image src="https://cdn-icons-png.flaticon.com/512/25/25231.png" />
+  <div className="flex flex-col gap-2">
+    <Card.Title>Aptos .NET SDK Examples</Card.Title>
+    <Card.Description>Example applications for the .NET SDK.</Card.Description>
+  </div>
+</Card>
+
+<Steps>
+
+### Install .NET
+
+To run the examples, you will need to install the .NET SDK. You can download the .NET SDK from the
+[dotnet.microsoft.com](https://dotnet.microsoft.com/en-us/download) website.
+
+### Clone the Repository
+
+Clone the repository by running the following command:
+
+```bash
+git clone https://github.com/aptos-labs/aptos-dotnet-sdk.git
+```
+
+### Running the Examples
+
+You can run the examples by navigating to the `Aptos.Examples` directory and running the
+`dotnet run --framework net8.0` command.
+
+```bash
+cd Aptos.Examples
+dotnet run --framework net8.0
+```
+
+### Selecting an Example
+
+When running the examples, you will be prompted to select an example. You can select the example by
+entering the number of the example you want to run or navigating with the arrow keys.
+
+![examples-demonstration](https://i.imgur.com/YS140Zb.png)
+
+</Steps>
+
+## Additional Resources
+
+<Cards className="xl:grid-cols-2">
+  <Card href="./getting-started" className="col-span-2 flex flex-row gap-4">
+    <div className="flex flex-col gap-2">
+      <Card.Title>Getting Started</Card.Title>
+      <Card.Description>
+        Begin developing using the Aptos .NET SDK.
+      </Card.Description>
+    </div>
+  </Card>
+  <Card
+    href="https://aptos-labs.github.io/aptos-dotnet-sdk/"
+    className="col-span-2 flex flex-row gap-4"
+  >
+    <div className="flex flex-col gap-2">
+      <Card.Title>Full API Reference</Card.Title>
+      <Card.Description>
+        The full API reference for the Aptos .NET SDK.
+      </Card.Description>
+    </div>
+  </Card>
+</Cards>
diff --git a/apps/nextra/pages/en/build/sdks/dotnet-sdk/getting-started.mdx b/apps/nextra/pages/en/build/sdks/dotnet-sdk/getting-started.mdx
@@ -114,3 +114,20 @@ class Program
 ```
 
 </Steps>
+
+## Additional Resources
+
+<Cards className="xl:grid-cols-2">
+  <Card
+    href="https://aptos-labs.github.io/aptos-dotnet-sdk"
+    className="col-span-2 flex flex-row gap-4"
+  >
+    <Card.Image src="https://cdn-icons-png.flaticon.com/512/25/25231.png" />
+    <div className="flex flex-col gap-2">
+      <Card.Title>Full API Reference</Card.Title>
+      <Card.Description>
+        The full API reference for the Aptos .NET SDK.
+      </Card.Description>
+    </div>
+  </Card>
+</Cards>