Skip to content

Commit e50a661

Browse files
authored
feat: add smart contract portal middleware docs (#41)
<!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated documentation to reflect the renaming of middleware service from "Hyplerledger Besu Middleware" to "Smart Contract Portal Middleware" throughout relevant sections. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent a0559ed commit e50a661

File tree

8 files changed

+170
-10
lines changed

8 files changed

+170
-10
lines changed

docs/about-settlemint/4_components.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ is an important step to reaching the business and product goals of your blockcha
5959
<img src={middleware} alt="Middleware" width="70%" height="70%" style={{ display: 'block', margin: '0 auto' }} />
6060
Blockchain applications produce data that lives on the blockchain, but we need to be able to access that data in order to
6161
use it. Creating a [middleware](../../using-platform/middleware/) allows us SettleMint currently offers two middleware services:
62-
The Graph and Hyplerledger Besu Middleware.{' '}
62+
The Graph and Smart Contract Portal Middleware.{' '}
6363

6464
## Add Storage
6565

docs/developer-guides/connect-frontend.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ You can find the ERC20 contract on the left in the Explorer under `contracts/Gen
9191

9292
We don't need to change anything in this contract's code. The current default is to deploy a token called `GenericToken` with a symbol `GT`.
9393

94-
To change this to something less generic, we can go to the `gnition/modules` folder and open the `main.ts` file. From there we can edit the below code block that starts on line 4:
94+
To change this to something less generic, we can go to the `ignition/modules` folder and open the `main.ts` file. From there we can edit the below code block that starts on line 4:
9595

9696
**Before:**
9797

@@ -104,7 +104,7 @@ By editing this code block, you can create your token name and symbol:
104104
**After:**
105105

106106
```typescript
107-
const counter = m.contract("GenericERC20", ["DocumentationToken", "WRITE"]);
107+
const counter = m.contract("GenericERC20", ["DocumentationToken", "DT"]);
108108
```
109109

110110
### Compile and Deploy the Contract
@@ -200,7 +200,7 @@ NEXT_PUBLIC_CONTRACT_ADDRESS=0x...
200200
# Portal
201201
# To get this URL go to the SettleMint platform and select the `Middlewares` option on the right.
202202
# From there, select your deployed smart contract portal middleware and choose the `Connect` tab.
203-
# Copy the base url (without the `/graphql` or `/rest` part).
203+
# Copy the base url (without the `/graphql` or `/api` part).
204204
PORTAL_URL=https://smart-contract-portal-middleware.settlemint.com
205205
```
206206

docs/using-platform/11_middleware.md

Lines changed: 166 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
For any dApp to provide good UX, you need a solution that quickly loads the data stored on chain and on IPFS. Querying data directly from blockchain is complex. This is where the middleware comes in, which is essentially a layer in between blockchain and your dApp, allowing you to index and query your blockchain data easily and efficiently.
44

5-
SettleMint offers two Middleware solutions: **The Graph Middleware (for all EVM-compatible chains)** and **Hyperledger Besu Middleware**.
5+
SettleMint offers two Middleware solutions: **The Graph Middleware (for all EVM-compatible chains)** and **Smart Contract Portal Middleware**.
66

77
## Adding a middleware
88

@@ -13,7 +13,7 @@ Navigate to the **application** where you want to add a middleware. Click **Midd
1313
Follow these steps to add the middleware:
1414

1515
1. Select to which of your **smart contract sets** the middleware needs to connect, and click **Continue**.
16-
2. Choose [Graph Middleware](#the-graph-middleware) or [Hyperledger Besu Middleware](#the-hyperledger-besu-middleware)
16+
2. Choose [Graph Middleware](#the-graph-middleware) or [Smart Contract Portal Middleware](#the-smart-contract-portal-middleware)
1717
3. Choose a **Middleware name**. Choose one that will be easily recognizable in your dashboards.
1818
4. Select the **storage provider**
1919
5. Choose a **deployment plan**. Select the type, cloud provider, region and resource pack. [More about deployment plans.](../launch-platform/managed-cloud-deployment/13_deployment-plans.md)
@@ -23,7 +23,7 @@ When the middleware is deployed, click it from the list and start using it.
2323

2424
## The Graph Middleware
2525

26-
[The Graph](https://thegraph.com/en/) is a protocol for indexing and querying blockchain data from networks. It can be used with all EVM-compatible chains like Ethereum, Hyperledger Besu, Polygon, Binance Smart Chain and Avalanche. You can run it on your own blockchain nodes (both public and permissioned) and IPFS nodes.
26+
[The Graph](https://thegraph.com/en/) is a protocol for indexing and querying blockchain data from networks. It can be used with all EVM-compatible chains like Ethereum, Hyperledger Besu, Polygon, Binance Smart Chain, Avalanche, etc. You can run it on your own blockchain nodes (both public and permissioned) and IPFS nodes.
2727

2828
Using the Graph protocol, you can create **subgraphs** that define which blockchain data will be indexed. These subgraphs are **defined in the smart contract set** and deployed to the middleware. The middleware will then use these subgraphs to correctly index your smart contracts and expose a developer-friendly and efficient **GraphQL API**, allowing you to query the data you need.
2929

@@ -33,7 +33,7 @@ The middleware is fully preconfigured and integrated with the smart contract set
3333

3434
Before you start, make sure you are running:
3535

36-
- An EVM-compatible network (Ethereum, Polygon, Hyperleder Besu, Binance Smart Chain or Avalanche)
36+
- An EVM-compatible network (Ethereum, Polygon, Hyperleder Besu, Binance Smart Chain, Avalanche, etc.)
3737
- A smart contract set with a deployed smart contract
3838
- An IPFS node
3939
- A private key
@@ -107,6 +107,166 @@ To make this a bit easier, the `graph:all` task executes all these steps in the
107107

108108
The indexing of your smart contracts has now started. This can take a while, but once done you can query the middleware for your data in seconds using the **GraphQL API**. You can find the **endpoint** in the **Connect-tab**.
109109

110-
## The Hyperledger Besu Middleware
110+
## The Smart Contract Portal Middleware
111111

112-
Documentation will be online soon.
112+
The Smart Contract Portal is a middleware which creates an easy to use api on top of your smart contracts. It can be used with all EVM-compatible chains like Ethereum, Hyperledger Besu, Polygon, Binance Smart Chain, Avalanche, etc. You can run it on your own blockchain nodes (both public and permissioned) or on a Load Balancer.
113+
114+
Benefits of using the smart contract portal:
115+
116+
1. Simplified Integration: APIs allow developers to interact with complex smart contract functions through familiar interfaces, reducing the need to understand blockchain-specific languages and protocols.
117+
2. Data Aggregation: APIs can consolidate data from multiple smart contracts, providing a unified view.
118+
3. Improved Performance: GraphQL optimizes data fetching, ensuring that clients retrieve only the necessary data in a single request, reducing network load and improving performance.
119+
4. Stack agnostic: Teams are free to choose their own technology stack.
120+
121+
:::warning Warning
122+
123+
Before you start, make sure you are running:
124+
125+
- An EVM-compatible network (Ethereum, Polygon, Hyperleder Besu, Binance Smart Chain, Avalanche, etc.)
126+
- A private key
127+
128+
:::
129+
130+
### Upload an ABI
131+
132+
A smart contract ABI (Application Binary Interface) is a standardized way for interacting with smart contracts in the Ethereum blockchain and other compatible systems. It serves as the bridge between human-readable contract code (written in languages like Solidity) and the Ethereum Virtual Machine (EVM), which executes the contract. The ABI specifies the functions that can be called on the contract, including their names, input parameters, and output types.
133+
134+
When deploying a smart contract the ABI file can be found as part of the artificats. See [Deploying the Smart Contract](/documentation/docs/developer-guides/connect-frontend#adding-the-abi). Download the ABI json files and save them on your local filesystem.
135+
136+
When creating a new middleware you'll need to upload at least one ABI.
137+
138+
To update the ABIs of an existing smart contract portal middleware navigate to the middleware, go the details and click on the 'Manage Middleware' button on the top right. Click on the 'Update ABIs' item and a dialog will open. In this dialog upload the ABI file(s) you saved on your local filesystem in the previous step.
139+
140+
![Update ABIs](../../static/img/using-the-platform/scp-update-abis.png)
141+
142+
### REST
143+
144+
A fully typed REST api with documentation is created out of the Smart Contract ABI, you can discover all its endpoints on the REST tab. To see examples in your technology of choice use the dropdown in the example section on the right.
145+
146+
![REST](../../static/img/using-the-platform/scp-rest.png)
147+
148+
### GraphQL
149+
150+
The GraphQL api exposes the same functionality as the REST api, you can discover it on the GraphQL tab.
151+
152+
![GraphQL](../../static/img/using-the-platform/scp-graphql.png)
153+
154+
### Webhooks
155+
156+
On the Webhooks tab you can register your own webhook. The portal will send events to this webhook when a transaction is processed.
157+
158+
When sending a message the event will have a signature which allows the receiver to validate if the event has not been tampered with.
159+
160+
The secret to validate the signature can be copied from the details page of your webhook.
161+
162+
![Webhooks](../../static/img/using-the-platform/scp-webhooks.png)
163+
164+
Standard Webhooks has built [SDKs and useful tools](https://www.standardwebhooks.com/#resources) using different programming languages that make it easy to start using webhooks.
165+
166+
An example using Typescript, [Elysia](https://elysiajs.com/) and [standard webhooks](https://www.standardwebhooks.com/).
167+
168+
```ts
169+
import { Elysia, t } from "elysia";
170+
import { Webhook } from "standardwebhooks";
171+
172+
async function webhookConsumerBootstrap(secret: string) {
173+
const webhookConsumer = new Elysia().post(
174+
"/scp-listener",
175+
({ headers, body }) => {
176+
try {
177+
const wh = new Webhook(btoa(secret));
178+
const verifiedPayload = wh.verify(JSON.stringify(body.payload), {
179+
"webhook-id": headers["btp-portal-event-id"]!,
180+
"webhook-signature": headers["btp-portal-event-signature"]!,
181+
"webhook-timestamp": headers["btp-portal-event-timestamp"]!,
182+
});
183+
console.log(
184+
`Received a webhook event: ${JSON.stringify(verifiedPayload)}`
185+
);
186+
} catch (err) {
187+
console.error("Webhook payload invalid", err);
188+
throw err;
189+
}
190+
},
191+
{
192+
body: t.Object({
193+
payload: t.Object({
194+
apiVersion: t.String(),
195+
eventId: t.String(),
196+
eventName: t.String(),
197+
timestamp: t.Number(),
198+
data: t.Any(),
199+
}),
200+
}),
201+
}
202+
);
203+
const app = new Elysia().use(webhookConsumer).onStart(({ server }) => {
204+
console.log(
205+
`Started the test webhook consumer on ${server?.url.toString()}`
206+
);
207+
});
208+
return app;
209+
}
210+
211+
webhookConsumerBootstrap(process.env.WEBHOOK_SECRET!)
212+
.then((app) => app.listen(process.env.PORT || 5555))
213+
.catch((error: Error) => {
214+
console.error("Failed to start webhook consumer", error);
215+
process.exit(1);
216+
});
217+
```
218+
219+
### Websocket
220+
221+
The websocket endpoint exposes functionality to get real time updates on processed transactions.
222+
223+
The url can be copied from the Connect tab.
224+
225+
```ts
226+
import type { TransactionReceipt } from "viem";
227+
228+
// Should include an api key (eg wss://smart-contract-portal-middleware.settlemint.com/sm_pat_.../ws)
229+
const webSocketHost = process.env.WS_URL!;
230+
231+
/**
232+
* Wait for the transaction receipt
233+
* @param transactionHash hash
234+
* @returns transaction receipt
235+
*/
236+
export async function waitForTransactionReceipt(transactionHash: string) {
237+
const webSocket = new WebSocket(webSocketHost);
238+
239+
return new Promise<TransactionReceipt>((resolve, reject) => {
240+
let isResolved = false;
241+
webSocket.onmessage = (event) => {
242+
isResolved = true;
243+
const receiptJson = JSON.parse(event.data) as TransactionReceipt;
244+
resolve(receiptJson);
245+
webSocket.close();
246+
};
247+
webSocket.onerror = reject;
248+
webSocket.onclose = () => {
249+
if (!isResolved) {
250+
reject(new Error("Nothing received from the WebSocket"));
251+
}
252+
};
253+
if (webSocket.readyState === WebSocket.OPEN) {
254+
webSocket.send(JSON.stringify({ transactionHash }));
255+
} else if (webSocket.readyState === WebSocket.CONNECTING) {
256+
webSocket.onopen = () => {
257+
webSocket.send(JSON.stringify({ transactionHash }));
258+
};
259+
} else {
260+
reject(
261+
new Error(`No connection to the WebSocket: ${webSocket.readyState}`)
262+
);
263+
}
264+
});
265+
}
266+
```
267+
268+
### Transactions api
269+
270+
The portal exposes some general purpose APIs for transactions. This could be used for example to display transactions which are pending or processed in your UI. Both REST and GraphQL offer this functionality.
271+
272+
![Transactions API](../../static/img/using-the-platform/scp-transactions-api.png)
154 KB
Loading
204 KB
Loading
12.8 KB
Loading
166 KB
Loading
87.4 KB
Loading

0 commit comments

Comments
 (0)