4m00se — web3-enabled form widgets builder

See the official website for the details on the application, its architecture, philosophy, and also the user guides and the developer guides.

Table of Contents

• Introduction
• Features
• Technology Stack
• Installation
• Usage
• Project Structure
• Contributing
• License

Introduction

4m00se is a decentralized-by-default application designed to provide a seamless experience for creating and managing forms, both on the blockchain, and outside of it (pure habitual web2 flow). It leverages the power of decentralized storage (IPFS via Pinata) and blockchain technology (Stellar/Soroban) to ensure data integrity and security, but also allows to work with JSON directly and use HTML widgets with custom user-provided callbacks.

Major features

• WYSIWYG Form builder: Create custom forms with ease via simple web interface.
• Embeddable widgets: Easily embed forms you'd built into web pages and applications via simple unique HTML code snippets.
• Form submission reader: Read and manage form responses for each of the forms.
• Decentralized storage: All form data (both config and user responses) can be stored as transactions on the Stellar network and linked to IPFS for JSON storage itself.

Technology Stack

• Frontend:

  • SvelteKit
  • TypeScript
  • Vite
  • VitePress (the documentation)
  • MDsveX (the blog)
  • PicoCSS

• Embeddable Widget:

  • Svelte
  • TypeScript
  • markdown-it
  • PicoCSS
  • Rollup

• Authentication:

  • Freighter Wallet API

• Data Storage:

  • Stellar Network API/SDK
  • IPFS (via Pinata API/SDK)

Installation

Prerequisites

• Rust environment for Soroban smart contracts, and Stellar CLI, see the official guide for reference
• Node.js v20 or later (with npm), you can use NVM with the included .nvmrc
• Reading the starter guides from the official Stellar documentation for writing smart contracts and building dapp frontends gives good context for working with the technologies
• The approach of building Soroban contract TS clients is shortly described here

Steps

1. Clone the repository:

git clone git@github.com:stellar-dapps/4m00se-dapp.git
cd 4m00se-dapp

2. Install dependencies:

npm install

3. Copy and populate required environment variables

cp .env.example .env

4. [Optional] Initialize environment for smart contracts, as mentioned above, if it's not there yet

npm run setup-environment

5. [Optional] Initiate the contracts and their TS clients for the dapp to work with (included into the previous step so not necessary if it was run already, but also can be run separately for existing Rust/Soroban environment)

node scripts/initialize.js

6. [Optional but recommended] Build the documentation pages

npm run build:docs

7. [Optional] Build widget bundle

npm run build:widget

8. Start the development server

npm run dev

Usage

Form Builder

• Navigate to the form builder page and log in via browser's Freighter wallet extension (use testnet).
• Create a new form by adding fields and configuring options.
• Preview and save the form.
• Get embeddable widget code and instructions.

Form Responses

• Navigate to the form responses subpage.
• View and manage form submissions.

Embeddable Widget

1. Include the widget from CDN in your application by adding the following script tag

<script src="https://4m.lol/widget/4m00s.js"></script>

2. Initialize the widget with the desired configuration

<div id="4m00se-widget-container"></div>
...
<script>
  formWidgetSDK.initFormWidget({
    <!-- see the "Form configuration" guide -->
  });
</script>

3. Form configuration

You can configure the following parameters of a form widget:

• configUrl — required, generated when a form is built
• container — optional, gives the possibility to use custom container id instead of the default 4m00se-widget-container
• onSubmit — optional, gives the possibility to use custom callback on form submission (by default, dedicated Freighter transaction signing flow is triggered)

Examples

See /static/demo/... for real-life usage example(s).

Project Structure

4m00se-dapp/
├── contracts/
│   └── hello_world
│       ├── src
│       │   ├── lib.rs
│       │   └── test.rs
│       └── Cargo.toml
├── docs/
│   └── ...
├── packages/
│   └── ...
├── scripts/
│   └── ...
├── src/
│   └── blogposts/
│   │   └── ...
│   └── contracts/
│   │   ├── ...
│   │   └── util.ts
│   ├── lib/
│   │   ├── components/
│   │   ├── content/
│   │   ├── models/
│   │   ├── stores/
│   │   └── utils/
│   ├── routes/
│   │   ├── ...
│   │   ├── api/
│   │   ├── +layout.svelte
│   │   └── +page.svelte
│   └── widget/
│   │   ├── FormWidget.svelte
│   │   ├── init-form-widget.ts
│   │   └── ...
│   ├── app.css
│   ├── app.d.ts
│   ├── app.html
│   └── env.d.ts
├── static/
│   ├── demo/
│   └── ...
├── Cargo.toml
├── package.json
├── rollup.config.js
├── svelte.config.js
├── vite.config.ts
└── ...

Contributing

Contributions are welcome! Please refer to CONTRIBUTING.md.

License

This project is licensed under the Apache-2.0 license. See the LICENSE file for details.