.near
account receives a subdomain under https://near.page.thewiki.near
serves https://thewiki.near.page.You only need to deploy single smart contract using WebAssembly to host your app HTTP backend, static resources and blockchain logic.
There is an HTTP gateway to NEAR blockchain which allows smart contract to handle arbitrary GET requests.
Every smart contract on NEAR also gets corresponding API endpoint which can be accessed through regular HTTP requests.
export function web4_get(request: Web4Request): Web4Response {
if (request.path == '/test') {
// Render HTML with form to submit a message
return htmlResponse(form({ action: "/web4/contract/guest-book.testnet/addMessage" }, [
textarea({ name: "text" }),
button({ name: "submit" }, ["Post"])
]));
}
if (request.path == '/messages') {
const getMessagesUrl = '/web4/contract/guest-book.testnet/getMessages';
// Request preload of dependency URLs
if (!request.preloads) {
return preloadUrls([getMessagesUrl]);
}
// Render HTML with messages
return htmlResponse('messages: ' + util.bytesToString(request.preloads.get(getMessagesUrl).body)!);
}
if (request.accountId) {
// User is logged in, we can welcome them
return htmlResponse('Hello to <b>' + request.accountId! + '</b> from <code>' + request.path + '</code>');
}
// Demonstrate serving content from IPFS
if (request.path == "/") {
return bodyUrl('ipfs://bafybeib72whzo2qiore4q6sumdteh6akewakrvukvqmx4n6kk7nwzinpaa/')
}
// By default return 404 Not Found
return status(404);
}
Basically smart contract just needs to implement web4_get
method to take in and return data in specific format.
@nearBindgen
class Web4Request {
accountId: string | null;
path: string;
params: Map<string, string>;
query: Map<string, Array<string>>;
preloads: Map<string, Web4Response>;
}
@nearBindgen
class Web4Response {
contentType: string;
status: u32;
body: Uint8Array;
bodyUrl: string;
preloadUrls: string[] = [];
cacheControl: string;
}
You can load any required data in web4_get
by returning list of URLs to preload in preloadUrls
field.
E.g. contract above preloads /web4/contract/guest-book.testnet/getMessages
. This class getMessages
view method on guest-book.testnet
contract.
After data is preloaded web4_get
gets called again with loaded data injected into preloads
.
You can post transaction by making a POST request to corresponding URL.
E.g contract above preloads has form that gets posted to /web4/contract/guest-book.testnet/addMessage
URL. This URL submits transaction which calls addMessage
method on guest-book.testnet
contract.
Note that both JSON and form data are supported. When transaction is processed by server user gets redirected to wallet for signing this transaction.
In future there is a plan to allow sending app-specific key as a cookie to sign limited subset of transactions without confirmation in wallet.
By default all HTML responses can be cached for 1 minute (assumed dynamic content). All images, videos, audio and CSS can be cached for 1 day (assumed static content).
You can override this by setting cacheControl
field in response.
It's not recommended to cache content for too long as then it not going to be hot on IPFS gateway.
Check out sample web4 project made with Rust.
You can access your deployed smart contract on https://near.page. This is hosted web4 gateway provided to all .near
accounts. For now it's free, but in future you might have to pay depending on how much traffic you get.
Every contract gets corresponding domain, e.g. check out https://web4.near.page rendered by web4.near
contract.
This works same as near.page
but for contracts deployed on testnet. Every account.testnet
gets corresponding account.testnet.page
domain.
mkcert -install
*.near.page
SSL certificate:mkcert "*.near.page"
web4
man-in-the-middle proxy locally:IPFS_GATEWAY_URL=https://ipfs.near.social NODE_ENV=mainnet WEB4_KEY_FILE=./_wildcard.near.page-key.pem WEB4_CERT_FILE=./_wildcard.near.page.pem npx web4-near
http://localhost:8080/
or to use localhost:8080
as an HTTPS proxy server.NODE_ENV
- mainnet
or testnet
to select network ID to use with NEAR config and key storeIPFS_GATEWAY_URL
- URL of IPFS gateway to use for ipfs://
URLsWEB4_KEY_FILE
- path to SSL key fileWEB4_CERT_FILE
- path to SSL certificate filePORT
- port to listen on (default: 3000
)PROXY_PORT
- port to listen on for proxy requests (default: 8080
). HTTPS MITM proxy is run on this port when WEB4_KEY_FILE
and WEB4_CERT_FILE
are provided.FAST_NEAR_URL
- URL of fast-near RPC server to use for NEAR API. Overrides NEAR RPC config selected by NODE_ENV
.This project aims to make trade offs based on these priorities:
npx
web4_raw_get
)