To mitigate this, the Endgame protocol would need to reject any incoming Seaport orders that were set to PARTIAL_RESTRICTED. Since all data coming from Seaport to the Endgame protocol occurs via a Seaport Zone contract, using the ZoneParameters struct for all the data, this mitigation should be as easy as checking the struct for the orderType and rejecting the fulfillment, right?

Well... not exactly. Much to my dismay, Seaport Core v1.5 doesn't expose the orderType of the order on its own. If I wanted to access the orderType, I would have to fork Seaport.

This blog post will be an overview of how I did that, and will hopefully help unlock some of the interesting tricks that the optimized Seaport contracts use under the hood.

Let's get started!

A Seaport zone contract is a permission-less extension of the Seaport protocol which can be implemented by a 3rd party. The signer of an order gets the option of whether they want to include that zone as part of the execution of the order.

The zone will execute its logic only after all token swaps in the order have occurred. This gives the zone contract the final say on whether the order should be fulfilled or not. Intuitively, you can think of zones as hooks for the Seaport protocol.

The Zone interface exposes one public function which must be implemented for the Seaport core contract to call:

interface ZoneInterface {
    /**
     * @dev Validates an order.
     *
     * @param zoneParameters The context about the order fulfillment and any
     *                       supplied extraData.
     *
     * @return validOrderMagicValue The magic value that indicates a valid
     *                              order.
     */
    function validateOrder(
        ZoneParameters calldata zoneParameters
    ) external returns (bytes4 validOrderMagicValue);
}

And its ZoneParameters are as follows:

struct ZoneParameters {
    bytes32 orderHash;
    address fulfiller;
    address offerer;
    SpentItem[] offer;
    ReceivedItem[] consideration;
    bytes extraData;
    bytes32[] orderHashes;
    uint256 startTime;
    uint256 endTime;
    bytes32 zoneHash;
}

For the purposes of Endgame, I would need to include a new parameter called orderType which could be tacked onto the ZoneParameters struct.

So, where in the weeds of the Seaport protocol does it make its call to a zone contract? The answer can be found in the ZoneInteraction.sol contract.

Inside, there is a function _assertRestrictedAdvancedOrderValidity which will manually build up the calldata for the zone interaction and then make the call. A truncated version, with only the parts we care about, looks like this:

function _assertRestrictedAdvancedOrderValidity(
    AdvancedOrder memory advancedOrder,
    bytes32[] memory orderHashes,
    bytes32 orderHash
) internal {
    // Declare variables that will be assigned based on the order type.
    address target;
    uint256 errorSelector;
    MemoryPointer callData;
    uint256 size;

    // Retrieve the parameters of the order in question.
    OrderParameters memory parameters = advancedOrder.parameters;

    // ... 

    // Encode the `validateOrder` call in memory.
    (callData, size) = _encodeValidateOrder(orderHash, parameters, advancedOrder.extraData, orderHashes);

    // ...

    // Perform call and ensure a corresponding magic value was returned.
    _callAndCheckStatus(target, orderHash, callData, size, errorSelector);
}

We can see that _encodeValidateOrder returns the calldata for a CALL to the validateOrder function on the ZoneInterface. This calldata can then be executed by _callAndCheckStatus.

Let's now turn to _encodeValidateOrder.

Now, we find ourselves inside the ConsiderationEncoder.sol contract to get a better look at _encodeValidateOrder.

Let's start by reviewing the first few lines of code in the function:

function _encodeValidateOrder(
    bytes32 orderHash,
    OrderParameters memory orderParameters,
    bytes memory extraData,
    bytes32[] memory orderHashes
) internal view returns (MemoryPointer dst, uint256 size) {
    // Get free memory pointer to write calldata to. This isn't allocated as
    // it is only used for a single function call.
    dst = getFreeMemoryPointer();

    // Write validateOrder selector and get pointer to start of calldata.
    dst.write(validateOrder_selector);
    dst = dst.offset(validateOrder_selector_offset);

    // ...logic continues on
}

That got complicated very quickly. The first thing to notice is the return type of MemoryPointer. This is just a custom type wrapper around a uint256, and points to the address in memory where this constructed calldata will reside. And, by returning its size as well, the full calldata can be extracted from memory when needed.

Additionally, Seaport has a few helper functions such as write and offset which makes interacting directly with memory a bit easier to understand. For example, the write implementation looks like this:

function write(MemoryPointer mPtr, uint256 value) internal pure {
    assembly {
        mstore(mPtr, value)
    }
}

To start, we can see that the free memory pointer has been obtained, and that the selector for validateOrder has been added to it. Once it has been added, the current pointer dst is incremented forward in memory by an offset which is equal in size to the selector.

With the selector added, we can skip around a bit in this function to see how the values of the ZoneParameters struct are added to the calldata as well.

Let's look at how the offerer value is added.

// Get the memory pointer to the order parameters struct.
MemoryPointer src = orderParameters.toMemoryPointer();

// Copy offerer to zoneParameters.
dst.offset(ZoneParameters_offerer_offset).write(src.readUint256());

Again, we can see that the offset here is used to figure out where, in memory, the offerer address should be copied. By doing this for all inputs to the ZoneParameters, the calldata will be completely built up and ready to execute.

Since we want to add orderType to the ZoneParameters struct, let's see how that would look:

struct ZoneParameters {
    bytes32 orderHash;
    address fulfiller;
    address offerer;
    SpentItem[] offer;
    ReceivedItem[] consideration;
    bytes extraData;
    bytes32[] orderHashes;
    uint256 startTime;
    uint256 endTime;
    bytes32 zoneHash;
    OrderType orderType; // <-- new field added
}

Because all offsets in memory for this struct are hardcoded, we will need to insert a new offset so that we can know where to place the OrderType.

uint256 constant ZoneParameters_orderHash_offset = 0x00;
uint256 constant ZoneParameters_fulfiller_offset = 0x20;
uint256 constant ZoneParameters_offerer_offset = 0x40;
uint256 constant ZoneParameters_offer_head_offset = 0x60;
uint256 constant ZoneParameters_consideration_head_offset = 0x80;
uint256 constant ZoneParameters_extraData_head_offset = 0xa0;
uint256 constant ZoneParameters_orderHashes_head_offset = 0xc0;
uint256 constant ZoneParameters_startTime_offset = 0xe0;
uint256 constant ZoneParameters_endTime_offset = 0x100;
uint256 constant ZoneParameters_zoneHash_offset = 0x120;
uint256 constant ZoneParameters_orderType_offset = 0x140; // <-- our new order type value
uint256 constant ZoneParameters_base_tail_offset = 0x160; // was 0x140, bumped to 0x160 to make room

The rest of the constant definitions can be found here.

Once the offset is in place, we can now extract the OrderType from the OrderParameters struct:

// Get the memory pointer to the order parameters struct.
MemoryPointer src = orderParameters.toMemoryPointer();

// ... arbitrary logic

// Write the OrderType into memory
dstHead.offset(ZoneParameters_orderType_offset).write(src.offset(OrderParameters_orderType_offset).readUint256());

And that should be everything! Seaport will now pass in our customized data during calls to ValidateOrder.

So close, yet so far. One of the hard things about constructing raw calldata is that if you don't get it right the first time, it can be impossible to try to debug. While testing my adjusted ZoneParameters struct with validateOrder(), I was getting inexplicable reverts each time I executed a Seaport order.

So what's the deal? To save you hours of hair-pulling, the issue lies in the hard-coded nature of how Seaport creates this calldata. Recall the validateOrder_selector which gets written to memory at the start of the encoding process.

Since we have changed the construction of the ZoneParameters struct, we also have changed the calculated value of the function selector for validateOrder(). By updating validateOrder_selector to the newly generated value, I was able to get the call to start succeeding again.

Now all that's left is a quick test to ensure everything is looking good. For this, we can start with a simple zone implementation that receives the ZoneParameters and assigns them to storage:

contract Zone {
    // public values to test against
    OrderType public orderType;
  
    function validateOrder(ZoneParameters calldata zoneParams) external returns (bytes4 validOrderMagicValue) {

        // store zone orderType
        orderType = zoneParams.orderType;

        // ... store all other zone parameters
    }
}

In our test, we can construct an order like so:

function test_Success_AssertRestrictedAdvancedOrderValidity() public {
    // ... setup logic occurs here

    // create the order parameters
    OrderParameters memory orderParameters = OrderParameters({
        // ...
        orderType: OrderType.FULL_RESTRICTED,
        // ...
    }); 

    // create the advanced order
    AdvancedOrder memory advancedOrder = AdvancedOrder({
        parameters: orderParameters,
        numerator: 1,
        denominator: 1,
        signature: "signature",
        extraData: "extraData"
    });

    // create the order hash
    bytes32 orderHash = keccak256("order hash");

    // create the order hashes
    bytes32[] memory orderHashes = new bytes32[](1);
    orderHashes[0] = orderHash;

    // make a call to the zone using the internal Seaport `validateOrder` calldata builder
    _assertRestrictedAdvancedOrderValidity(
        advancedOrder,
        orderHashes,
        orderHash
    );

    // Assert the orderType is expected
    assertEq(OrderType.FULL_RESTRICTED, zone.orderType());
}

Here we construct an order with a type of OrderType.FULL_RESTRICTED, and the test shows that the call was successfully made to the zone contract because the proper OrderType value was set in storage. You can view the full test here.

Hopefully this post has shed a bit of light on what it takes to fork seaport core and make small tweaks to it. The codebase is filled with low-level gems and I encourage you to poke around the repository as well.

This post focused on adjusting a single value in ZoneParameters. However, not included in this post is how I extended the ZoneParameters struct to include an array of all transfers that occur within a single order.

This technique required considerably more work because of the increase in complexity to encode arrays in calldata, and I felt that a tutorial on that would be a bit out of reach. But for the full source of the forked seaport core repo, you can view that here.

As always, if you have any questions about my forked Seaport core implementation, feel free to reach out to myself at alec@021.gg or on x.com.

What I’m not going to write about is testing philosophy. The discourse on why, what and how to test is saturated enough. I’ll just leave it at the following. I like tests. They provide confidence my code is working as intended. I like tests with a high ROI better than tests with a low ROI. In some cases TDD helps in designing an API. In most cases E2E is all you need.

In all cases one test is infinitely better than no test.

A long while back (over a year ago—84 years in web3 time), I wrote a piece on how we approached E2E testing for our v2 protocol application. The basic initial setup is still the same:

1. Playwright as the test runner.

2. Foundry’s Anvil for running a testnet node.

3. Wagmi & Viem to connect wallets and interface with the blockchain.

4. Leverage Wagmi’s mock connector to set up a testing wallet.

The previous article provided a get-running-quick tutorial. This one will be more in-depth. The goal is setting up a web3-ready Remix boilerplate with a big focus on E2E testing.

If you just want to see the code, there’s an example repository on GitHub you can check out.

Lets get this show on the road. The following will create a Remix starter repository:

npx create-remix@latest --yes blockchain-web-app-e2e-testing-remix-wagmi \
  && cd blockchain-web-app-e2e-testing-remix-wagmi

Make sure to install Viem, Wagmi and Tanstack Query as dependencies. We also need to install Playwright as a development dependency. And install Playwright’s browsers.

npm install --save-exact @tanstack/react-query viem wagmi
npm install --save-dev @playwright/test
npx playwright install

Grab the example configuration from playwright.dev and save it to the file playwright.config.ts. There is one tiny change we might want to make, which is the fullyParallel flag.

  ...
  // Run all tests in parallel.
  fullyParallel: false, 
  ...

The reason we probably want to switch this off is because, if fullyParallel is enabled, Playwright—assuming there are workers available—will not only execute separate test suites in parallel but also execute each test in a test suite in parallel. When testing against a blockchain there’s often a linearity to the tests, requiring you to execute things serially as opposed to fully parallel.

We will get back to this at the end of the article.

Lets add our first test in tests/smoke.spec.ts:

// tests/smoke.spec.ts
import { expect, test } from '@playwright/test';

test('load the homepage', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveTitle('New Remix App');
});

Update scripts in package.json to execute Playwright:

// package.json
    "start": "remix-serve ./build/server/index.js",
    "test": "playwright test", 
    "typecheck": "tsc

And run it:

npm run build
npm run test

Okay. One more thing. Notice the webServer.reuseExistingServer option in playwright.config.ts. This tells Playwright, if an existing process exposed on webServer.url returns a valid response, it won’t execute webServer.command. This allows us to run tests against our development server. Unfortunately, Vite uses :5173 as the port when executing it in development mode. Lets fix this by pinning the development server to host: '0.0.0.0' and port: 3000.

// vite.config.ts
export default defineConfig({
  plugins: [remix(), tsconfigPaths()],
  server: { host: '0.0.0.0', port: 3000 }, 
});

Alright, sparky! We can now run the test against the dev server. Get that running with npm run dev.

We need a local RPC node. Why do we need a local RPC node? Because testing on a live chain is anything but idempotent. With a local testnet node you can spin up a fresh blockchain state each run. It also enables you to snapshot and/or revert/restore the chain state. Moreover, it allows you to fork an EVM-compatible chain at a certain block number. All this tooling is essential for any serious testing of blockchain applications.

And, it will save you a whole load of gas.

We prefer Foundry’s Anvil, but if you’re familiar with Hardhat or Truffle the same principles and processes should apply, roughly. I’ll refer to the Foundry installation instructions to get it set up.

After installing Foundry, open a new terminal and execute anvil. This will boot up your testnet node to develop against.

Lets set up Wagmi. Create app/wagmi.ts and paste in the following:

// app/wagmi.ts
import { createClient, http } from "viem";
import { createConfig } from "wagmi";
import { injected } from "wagmi/connectors";
import { foundry, mainnet } from "wagmi/chains";

const chains = [mainnet, foundry] as const;

export const config = createConfig({
  chains,
  client: ({ chain }) => createClient({ chain, transport: http() }),
  connectors: [injected()],
  ssr: true, // you want this to avoid hydration errors.
});

The next step is setting up our Remix application to make use of our Wagmi configuration. Note that we’re putting the QueryClient in a useState because we need this to be unique for every visitor. If you’d use a non-useState initialized QueryClient the client would be shared by all visitors on the server-side parts of Remix. Anyway. We’re going to do the same for the Wagmi configuration because we want to change this on-the-fly later.

// app/root.tsx
import { QueryClientProvider, QueryClient } from "@tanstack/react-query"; 
import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
} from "@remix-run/react";
import { useState } from "react"; 
import { WagmiProvider } from "wagmi"; 

import { config } from "~/wagmi"; 

export function Layout({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(new QueryClient()); 
  const [wagmiConfig] = useState(config); 
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <QueryClientProvider client={queryClient}>
          <WagmiProvider config={wagmiConfig}>{children}</WagmiProvider>
        </QueryClientProvider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

export default function App() {
  return <Outlet />;
}

The last thing we want to do here is actually implement some blockchain interfacing so we can connect a wallet to the application and switch chains (if required). Lets change the app/_index.tsx completely so we can:

1. Connect a wallet

2. Display the address connected

3. Switch chains

As we’re changing the complete file, I’m adding the complete implementation below:

// app/_index.tsx
import type { MetaFunction } from "@remix-run/node";
import {
  useAccount,
  useConnect,
  useDisconnect,
  useSwitchChain,
  useChainId,
} from "wagmi";

export const meta: MetaFunction = () => {
  return [
    { title: "New Remix App" },
    { name: "description", content: "Welcome to Remix!" },
  ];
};

export default function Index() {
  const { address, isConnected } = useAccount();
  const chainId = useChainId();
  const { connectAsync, connectors } = useConnect();
  const { disconnect } = useDisconnect();
  const { chains, switchChainAsync } = useSwitchChain();
  return (
    <div style={{ fontFamily: "system-ui, sans-serif", lineHeight: "1.8" }}>
      <div style={{ padding: 16, border: "solid 1px" }}>
        <p>Connected: {address ?? "no"}</p>

        <p style={{ display: "flex", gap: 8 }}>
          Chain:
          {chains.map((chain) => (
            <button
              key={chain.id}
              onClick={() => void switchChainAsync({ chainId: chain.id })}
              type="button"
            >
              {chain.id === chainId && "✅"} {chain.name} ({chain.id})
            </button>
          ))}
        </p>

        <p style={{ display: "flex", gap: 8 }}>
          {isConnected ? (
            <button onClick={() => disconnect()} type="button">
              Disconnect
            </button>
          ) : (
            connectors.map((connector) => (
              <button
                key={connector.id}
                onClick={() => void connectAsync({ connector })}
                type="button"
              >
                {connector.name}
              </button>
            ))
          )}
        </p>
      </div>
    </div>
  );
}

Time to see what we have so far. Make sure you have the Remix dev server (npm run dev) and anvil (anvil) running. Lets see if we can connect a browser extension wallet like MetaMask. Note that in the demo below I imported the first available anvil testing account into MetaMask. Whenever you boot up anvil, by default it provides you with 10 testing accounts and their corresponding private keys.

Finally we’re getting to the meat. When attempting to conjure up a test for connecting a wallet we get stuck. There’s no easy way to add wallet functionality to Playwright. There are projects like Synpress and Dappeteer (deprecated at the time of writing) which wrap MetaMask. Personally I’m not a fan of this approach as it’s locking you into testing on a specific wallet. Any fundamental changes to MetaMask will require changes in your tests. Any fundamental breakages in MetaMask will break your tests. Icky.

The way we like to solve this is making use of Wagmi’s mock connector. The mock connector offers a fantastic low-level abstraction for connecting a wallet to a blockchain application. You can integrate it in your application to test wallet connections and interactions. It even allows you to test non-happy paths by passing error cases to its features option. This allows you to test errors when switching chains, connecting wallets, or signing messages or transactions.

We need to initialize the mock connector. There are several ways to do this. The simplest would be to add it to our list of connectors in app/wagmi.ts. The mock connector requires one argument with a list of accounts it’s able to use. Lets limit this to the first two test accounts provided by anvil:

// app/wagmi.ts
import { createClient, http } from "viem";
import { createConfig } from "wagmi";
import { injected, mock } from "wagmi/connectors"; 
import { foundry, mainnet } from "wagmi/chains";

const chains = [mainnet, foundry] as const;

export const config = createConfig({
  chains,
  client: ({ chain }) => createClient({ chain, transport: http() }),
  connectors: [ 
    injected(), 
    mock({ 
      accounts: [ 
        "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", 
        "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", 
      ], 
    }), 
  ], 
  ssr: true,
});

Yep. That adds it to our list of connectors:

And it allows us to connect with it. Woo!

Lets add a test where we connect the first account from the mock connector.

// tests/smoke.spec.ts
import { expect, test } from "@playwright/test";

test("load the homepage", async ({ page }) => {
  await page.goto("/");
  await expect(page).toHaveTitle("New Remix App");
});

test("connect wallet", async ({ page }) => { 
  await page.goto("/"); 
  await page.getByRole("button", { name: "Mock Connector" }).click(); 
  await expect( 
    page.getByText("Connected: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266") 
  ).toBeVisible(); 
}); 

When we run npm test, we should be green:

> test
> playwright test


Running 2 tests using 2 workers
  2 passed (1.1s)

Yep.

The catch here is that the mock connector is initialized for everyone—regardless of environment. If we were to build and deploy this people would be able to connect with it, which could be highly confusing. We could add some logic which initializes the mock connector only on development environments by checking Vite’s import.meta.env.DEV. This is what we did for our v2 protocol application and our previous example repository.

It works great, but there’s an opportunity here to make the mock connector useful for more than just testing.

You could say that the web is quite a volatile environment. Users have different systems, different configurations, different browsers, plugins, etc. I would argue web3 is an even more volatile environment. On top of different systems and configurations, there’s a wide variety of wallet providers and an even bigger variety of tokens held in these wallets.

One of the most powerful abilities you can give yourself and your team is being able to browse an application as any user. For Endgame we set up the mock connector in a way to allow us to do precisely this.

We expose an interface which swaps our production configuration with a configuration leveraging the mock connector. This allows us to initialize a mock connection from any arbitrary account. What’s more, through this interface we can pass options into the mock connector’s features configuration to test specific scenarios. Scenario’s like connection failure, user rejections, etc.

The goals here are:

1. Set up a function accepting a private key/address and the mock connector’s features options.

2. Expose this to the browser in some way. The path of least resistance (and least intrusion into the UI) is slapping it onto window.

3. Set up a Playwright fixture which initializes mock connector configuration in test environments.

The trick here is having the Wagmi configuration live inside React too. Remember how we wrapped it in a useState() earlier? We can access and expose its setter.

  const [wagmiConfig] = useState(config); 

What we need is a factory function which creates a new Wagmi configuration for us. The resulting configuration can be passed to a setWagmiConfig() state dispatcher. Because it’s part of React state, any update to this state makes parts of the application dependent on the configuration rerender automagically.

The configuration factory will need to mirror most of our general configuration. The key thing to set up is the account it will be initialized for. See the highlighted line.

// app/wagmi.ts
import { createClient, http, isAddress } from "viem"; 
import { privateKeyToAccount } from "viem/accounts"; 
import { createConfig } from "wagmi";
import { injected, mock, type MockParameters } from "wagmi/connectors"; 
import { foundry, mainnet } from "wagmi/chains";

const chains = [mainnet, foundry] as const;

export const config = createConfig({
  chains,
  client: ({ chain }) => createClient({ chain, transport: http() }),
  connectors: [injected()],
  ssr: true,
});

export function createMockConfig( 
  addressOrPkey: `0x${string}`, 
  features?: MockParameters["features"] 
) { 
  const account = isAddress(addressOrPkey) 
    ? addressOrPkey
    : privateKeyToAccount(addressOrPkey); 
  const address = typeof account === "string" ? account : account.address; 
  return createConfig({ 
    connectors: [mock({ accounts: [address], features })], 
    chains, 
    client: ({ chain }) => createClient({ account, transport: http(), chain }), 
    ssr: true, 
  }); 
} 

That’s the first part. The createMockConfig() function is set up to accept a private key or an address and the mock connector features configuration. By allowing any account address to be passed we can impersonate any account.

Next part is hooking this up to WagmiProvider initialization and slapping this helper onto the global window interface.

// app/root.tsx
import { QueryClientProvider, QueryClient } from "@tanstack/react-query";
import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
} from "@remix-run/react";
import { useCallback, useState } from "react"; 
import { WagmiProvider } from "wagmi";

import { config, createMockConfig } from "~/wagmi"; 

declare global { 
  interface Window { 
    _setupAccount: typeof createMockConfig; 
  } 
} 

export function Layout({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(new QueryClient());
  const [wagmiConfig, setWagmiConfig] = useState(config); 

  const _setupAccount = useCallback( 
    (...args: Parameters<Window["_setupAccount"]>) => { 
      const config = createMockConfig(...args); 
      setWagmiConfig(config); 
    }, 
    [] 
  ); 

  if (typeof window !== "undefined") window._setupAccount = _setupAccount; 

  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <QueryClientProvider client={queryClient}>
          <WagmiProvider config={wagmiConfig}>{children}</WagmiProvider>
        </QueryClientProvider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

export default function App() {
  return <Outlet />;
}

Lets test it out.

Cool. We can now browse our app pretending to be Vitalik.

Fixtures are one of the core concepts to grok in Playwright. They’re a very powerful tool, allowing you to abstract a lot of setup and application-specific initializations and interactions into a very simple interface.

Test fixtures are used to establish the environment for each test, giving the test everything it needs and nothing else. […] With fixtures, you can group tests based on their meaning, instead of their common setup.

When testing blockchain applications there are a few things which are very useful to have set up in fixtures:

• A Viem test client, extended with public- and wallet client actions.

• A date mocking mechanism so we can pretend it’s earlier or later.

• An account connection fixture so we don’t have to repeat this for each test.

In order to set up a Playwright fixture you want to grab test from @playwright/test and use its test.extend() method. When you export the extended test the fixture you’ve set up will be made available. In your tests, instead of importing Playwright’s test, you would import your own.

Let’s set up our first fixture. This one will concern itself with abstracting connecting a wallet through our mock connector. I’ll provide some more useful fixtures in the next section.

Lets create two files: tests/fixtures/wallet.ts and tests/fixtures/index.ts. The former will house our application-specific wallet connection initialization. The latter we’ll use as an entrypoint which re-exports anything from @playwright/test plus our extended test function.

// tests/fixtures/wallet.ts
import { type Page } from "@playwright/test";
import { type Address, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { test as base } from "@playwright/test";
import { type MockParameters } from "wagmi/connectors";

// It helps if we give accounts names, as it makes discerning
// different accounts more clear. It's easier to talk about
// Alice and Bob in tests than "wallet starting with 0xf39...".
// NOTE: These private keys are provided by `anvil`.
const ACCOUNT_PKEYS = {
  alice: "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
  bob: "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d",
} as const;

// A fixture doesn't need to be a class. It could just as well
// be a POJO, function, scalar, etc. In our case a class keeps
// things nice and organized.
export class WalletFixture {
  address?: Address;
  #page: Page;

  // The only thing we require for setting up a wallet connection
  // through the mock connector is the page to look up elements.
  constructor({ page }: { page: Page }) {
    this.#page = page;
  }

  // You can make this as contrived or expansive as required for
  // your use-case. For Endgame, we actually derive accounts from
  // an `ANVIL_MNEMONIC` env with viem's `mnemonicToAccount()`.
  async connect(
    name: keyof typeof ACCOUNT_PKEYS,
    features?: MockParameters['features']
  ) {
    const pkey = ACCOUNT_PKEYS[name];
    const account = privateKeyToAccount(pkey);

    this.address = account.address;

    await this.#setup(pkey, features);
    await this.#login();
  }

  // Any application-specific rituals to get a wallet connected
  // can be put here. In our demo app we click a button.
  async #login() {
    await this.#page.getByRole("button", { name: "Mock Connector" }).click();
  }

  // Remember how we slapped our mock configuration helper onto
  // `window._setupAccount`? Here's how to use it in Playwright:
  async #setup(...args: [Hex, MockParameters["features"]]) {
    // We let Playwright wait for the function to be non-nullable
    // on the `window` global. This ensures we can use it.
    await this.#page.waitForFunction(() => window._setupAccount);
    // `page.evaluate()` is a _very_ powerful method which allows
    // you to evaluate a script inside the browser page context.
    // In this example, we evaluate `window._setupAccount()`
    // with arguments passed from inside Playwright tests.
    await this.#page.evaluate((args) => window._setupAccount(...args), args);
  }
}

// Lastly, we export a `test` with the `WalletFixture` attached.
export const test = base.extend<{ wallet: WalletFixture }>({
  async wallet({ page }, use) {
    await use(new WalletFixture({ page }));
  },
});

The second file we’ll create is tests/fixtures/index.ts which will be a central module making fixtures and any other Playwright exports available to our tests:

// tests/fixtures/index.ts
import { mergeTests } from "@playwright/test";

import { test as walletTest } from "./wallet";

// Re-export anything from Playwright.
export * from "@playwright/test";
// Export our test function, extended with fixtures.
// It'll become useful when we have more fixtures to attach.
export const test = mergeTests(walletTest);

Now we can update our tests/smoke.spec.ts file to make use of this fixture:

// tests/smoke.spec.ts
// Notice how we're importing from './fixtures' now.
import { expect, test } from "./fixtures"; 
import { UserRejectedRequestError } from "viem"; 

test("load the homepage", async ({ page }) => {
  await page.goto("/");
  await expect(page).toHaveTitle("New Remix App");
});

test("connect wallet", async ({ page, wallet }) => { 
  await page.goto("/");
  await wallet.connect("alice"); 
  await expect(page.getByText(`Connected: ${wallet.address}`)).toBeVisible(); 
});

test("throw when wallet connect failure", async ({ page, wallet }) => {
  await page.goto("/"); 
  await Promise.all([ 
    page.waitForEvent( 
      "pageerror", 
      (error) => error.name === "UserRejectedRequestError"
    ), 
    wallet.connect("alice", { 
      connectError: new UserRejectedRequestError( 
        new Error("Connection failure.") 
      ), 
    }), 
  ]); 
}); 

Make sure you have the Remix dev server and anvil node running. Then, npm test 🤞

> test
> playwright test


Running 3 tests using 3 workers
  3 passed (1.5s)

Amazing.

With Endgame parts of our core functionality depend on time elapsed. Primarily, any rental has a rent duration which, well, dictates the amount of seconds a rental will be considered being actively rented. In order to test the temporal aspects of the protocol we need to travel forwards in time. This way, when a rental has “expired”, we can test functionality related to stopping rentals.

This kind of sucks, because we need to synchronize multiple time sources to reflect the same time. At the very least the chain’s block timestamp and the browser’s date.

In this bonus round we’ll implement a few Playwright fixtures which enables us to 1) mock the browser’s Date initializer and 2) synchronize our test RPC node so that the latest block timestamp reflects the same time.

First, lets add something to our UI so we can verify.

// app/_index.tsx
import type { MetaFunction } from "@remix-run/node";
import {
  useAccount,
  useConnect,
  useDisconnect,
  useBlock, 
  useSwitchChain,
  useChainId,
} from "wagmi";

export const meta: MetaFunction = () => {
  return [
    { title: "New Remix App" },
    { name: "description", content: "Welcome to Remix!" },
  ];
};

export default function Index() {
  const { address, isConnected } = useAccount();
  const chainId = useChainId();
  const { connectAsync, connectors } = useConnect();
  const { disconnect } = useDisconnect();
  const { chains, switchChainAsync } = useSwitchChain();

  const { data: block } = useBlock(); 
  const blockTime = new Date(Number(block?.timestamp) * 1000).toUTCString(); 
  const browserTime = new Date().toUTCString(); 

  return (
    <div style={{ fontFamily: "system-ui, sans-serif", lineHeight: "1.8" }}>
      <div style={{ padding: 16, marginBottom: 16, border: "solid 1px" }}>
        <p>Block time: {blockTime}</p>
        <p>Browser time: {browserTime}</p>
      </div>

      <div style={{ padding: 16, border: "solid 1px" }}>
        <p>Connected: {address ?? "no"}</p>

        <p style={{ display: "flex", gap: 8 }}>
          Chain:
          {chains.map((chain) => (
            <button
              key={chain.id}
              onClick={() => void switchChainAsync({ chainId: chain.id })}
              type="button"
            >
              {chain.id === chainId && "✅"} {chain.name} ({chain.id})
            </button>
          ))}
        </p>

        <p style={{ display: "flex", gap: 8 }}>
          {isConnected ? (
            <button onClick={() => disconnect()} type="button">
              Disconnect
            </button>
          ) : (
            connectors.map((connector) => (
              <button
                key={connector.id}
                onClick={() => void connectAsync({ connector })}
                type="button"
              >
                {connector.name}
              </button>
            ))
          )}
        </p>
      </div>
    </div>
  );
}

The result will look something like the screenshot below. When you boot up a new anvil instance these times will roughly correlate, but after a little while—refresh the page or force a rerender—these times will diverge more and more. Also note that blockTime relates to the currently selected chain. Switching between Ethereum and Foundry will reflect the latest block time on these respective chains.

It’s high time (ha!) to add some tooling to sync these up. We will create two more fixtures. One responsible for interfacing with anvil and another responsible for patching the Date constructor browser-side.

First up the anvil fixture:

// tests/fixtures/anvil.ts
import { test as base } from "@playwright/test";
import { createTestClient, http, publicActions, walletActions } from "viem";
import { foundry } from "viem/chains";

const anvil = createTestClient({
  chain: foundry,
  mode: "anvil",
  transport: http(),
})
  .extend(publicActions)
  .extend(walletActions)
  // `client.extend()` is a very low-barrier utility, allowing you
  // to write custom methods for a viem client easily. It receives
  // a callback with the `client` as argument, returning an object
  // with any properties or methods you want to tack on.
  // We return an object with an `async syncDate(date)` method.
  .extend((client) => ({
    async syncDate(date: Date) {
      await client.setNextBlockTimestamp({
        // NOTE: JavaScript Date.getTime returns milliseconds.
        timestamp: BigInt(Math.round(date.getTime() / 1000)),
      });
      // We need to mine a block to commit its next timestamp.
      return client.mine({ blocks: 1 });
    },
  }));

export const test = base.extend<{ anvil: typeof anvil }>({
  async anvil({}, use) {
    await use(anvil);
  },
});

Having an anvil fixture is generally useful as it allows you to query and interact with the test node inside of your tests.

The most pragmatic way to approach synchronizing date sources is to have the browser synchronize with block time. Flipping this approach—syncing a testnet node to the current system time—could be the better approach but aving block time be leading yields less and simpler code in the fixture.

We’re going to write a date fixture which will make use of our anvil fixture. In this date fixture we can use the anvil client to fetch the block time to synchronize the browser on. We will add two methods:

1. addDays(n) which will advance the current date n amount of days.

2. set(date) which will attempt to synchronize the block timestamp and browser Date constructor with the passed date.

Note the line which imports test from our ./anvil fixture.

// tests/fixtures/date.ts
import { test as base } from "./anvil"; 

export const test = base.extend<{
  date: {
    addDays: (days: number) => Promise<Date>;
    set: (value: number | string | Date) => Promise<Date>;
  };
}>({
  async date({ anvil, page }, use) {
    // We want to keep around a cached reference to be used
    // by `addDays()` as opposed to getting the current date
    // anew each time we call `addDays()`.
    let date = new Date();

    async function addDays(days: number) {
      date = new Date(date.setDate(date.getDate() + days));
      await set(date);
    }

    async function set(value: number | string | Date) {
      date = new Date(value);

      // Attempt to synchronize our test node's block timestamp
      // with the provided `date`. We can't set dates in the past
      // or at the current time: it will throw a Timestamp error.
      try {
        await anvil.syncDate(date);
      } catch (error) {
        console.error(error);
      }

      // Construct our patch to `window.Date`. Yes. We're
      // patching a global. Unfortunately this will mean React
      // will throw hydration warnings, but it will allow us
      // to test with mocked dates regardless.
      const dateInit = date.valueOf();
      const datePatch = `
      Date = class extends Date {
        constructor(...args) {
          super(...args.length ? args : [${dateInit}]);
        }

        now() {
          return super.now() + (${dateInit} - super.now());
        }
      };
      `;

      // Firstly we'll attach it as a `<script>` to the page
      // in Playwright. Whenever you `goto()` or `reload()` in
      // Playwright, the Date patch will be applied.
      await page.addInitScript(datePatch);
      // Secondly, we evaluate the script directly within the
      // Playwright page context. Roughly this should allow us
      // to forgo any `goto()` or `reload()`—assuming any
      // component sensitive to `Date` is rerendered before
      // doing your test assertions.
      await page.evaluate((datePatch) => {
        // Look, mom! A valid use of `eval()`!
        // eslint-disable-next-line no-eval
        eval(datePatch);
      }, datePatch);

      return date;
    }

    await use({ addDays, set });
  },
});

One more thing…

We can update our tests/fixtures/index.ts file to chuck all our created fixtures onto a single test() function.

// tests/fixtures/index.ts
import { mergeTests } from "@playwright/test";

import { test as anvilTest } from "./anvil"; 
import { test as dateTest } from "./date"; 
import { test as walletTest } from "./wallet";

export * from "@playwright/test";
export const test = mergeTests(anvilTest, dateTest, walletTest); 

We’re able to time travel now! Only forwards though.

Lets try it out and add a test.

// tests/smoke.spec.ts
import { expect, test } from "./fixtures";
import { UserRejectedRequestError } from "viem";

test("load the homepage", async ({ page }) => {
  await page.goto("/");
  await expect(page).toHaveTitle("New Remix App");
});

test("connect wallet", async ({ page, wallet }) => {
  await page.goto("/");
  await wallet.connect("alice");
  await expect(page.getByText(`Connected: ${wallet.address}`)).toBeVisible();
});

test("throw when wallet connect failure", async ({ page, wallet }) => {
  await page.goto("/");
  const [error] = await Promise.all([
    page.waitForEvent("pageerror"),
    wallet.connect("alice", {
      connectError: new UserRejectedRequestError(
        new Error("Connection failure.")
      ),
    }),
  ]);
  expect(error.name).toBe("UserRejectedRequestError");
});

test("synchronize times", async ({ date, page }) => { 
  await date.set("2069-04-20"); 
  await page.goto("/"); 
  await page.getByRole("button", { name: /Foundry/ }).click(); 
  await expect(page.getByText(/Block time/)).toHaveText(/Sat, 20 Apr 2069/); 
  await expect(page.getByText(/Browser time/)).toHaveText(/Sat, 20 Apr 2069/); 
  await date.addDays(69420); 
  // Because our demo app doesn't rerender after patching the
  // Date constructor we need a `goto()` or `reload()`.
  await page.reload(); 
  await expect(page.getByText(/Block time/)).toHaveText(/Sun, 15 May 2259/); 
  await expect(page.getByText(/Browser time/)).toHaveText(/Sun, 15 May 2259/); 
}); 

When you run npm test again, we should get 4 passed tests now. Running this command a second time however makes the "synchronize times" test fail. If you read the code in our date fixture carefully you may know why: we can’t set the time of our local testnet node to a date in the past. Only forwards.

The solution here is making a snapshot of our chain state before our tests fire and restore this snapshot after all tests are finished. We can leverage our anvil fixture for this.

// tests/smoke.spec.ts
import { expect, test } from "./fixtures";
import { UserRejectedRequestError } from "viem";

let id: `0x${string}` | undefined; 

test.beforeAll(async ({ anvil }) => { 
  id = await anvil.snapshot(); 
}); 

test.afterAll(async ({ anvil }) => { 
  if (!id) return; 
  await anvil.revert({ id }); 
  id = undefined; 
}); 

test("load the homepage", async ({ page }) => {
  await page.goto("/");
  await expect(page).toHaveTitle("New Remix App");
});

test("connect wallet", async ({ page, wallet }) => {
  await page.goto("/");
  await wallet.connect("alice");
  await expect(page.getByText(`Connected: ${wallet.address}`)).toBeVisible();
});

test("throw when wallet connect failure", async ({ page, wallet }) => {
  await page.goto("/");
  const [error] = await Promise.all([
    page.waitForEvent("pageerror"),
    wallet.connect("alice", {
      connectError: new UserRejectedRequestError(
        new Error("Connection failure.")
      ),
    }),
  ]);
  expect(error.name).toBe("UserRejectedRequestError");
});

test("synchronize times", async ({ date, page }) => {
  await date.set("2069-04-20");
  await page.goto("/");
  await page.getByRole("button", { name: /Foundry/ }).click();
  await expect(page.getByText(/Block time/)).toHaveText(/Sat, 20 Apr 2069/);
  await expect(page.getByText(/Browser time/)).toHaveText(/Sat, 20 Apr 2069/);
  await date.addDays(69420);
  await page.reload();
  await expect(page.getByText(/Block time/)).toHaveText(/Sun, 15 May 2259/);
  await expect(page.getByText(/Browser time/)).toHaveText(/Sun, 15 May 2259/);
});

Reboot your anvil node. Now you should be able to spam npm test as many times as you like—assuming you set fullyParallel: false in you playwright.config.ts.

Time to add a cherry on top.

Maybe you caught the fact that the Playwright configuration has a webServer option. The cool thing about webServer is that it can be leveraged as a poor-man’s service orchestration. webServer can be turned into an array of webServer entries, meaning we can add our anvil initialization here as well.

// playwright.config.ts
  webServer: [ 
    { 
      command: "anvil", 
      url: "http://127.0.0.1:8545", 
      reuseExistingServer: !process.env.CI, 
    }, 
    { 
      command: "npm run start", 
      url: "http://127.0.0.1:3000", 
      reuseExistingServer: !process.env.CI, 
    }, 
  ], 

Check it out.

Woah. This was quite the trip. I hope this walkthrough is helpful for some of you. It was definitely fun to write. I also hope the peak behind the curtain on how we approached testing challenges for Endgame is as enjoyable to read as it is to share.

Be sure to check out the example repository, which should be straightforward to get up and running. I think it’s a decent web3 front end development springboard. The commits to the repository roughly corroborate to each of the sections in this walkthrough.

If you have any questions or remarks, be sure to hit me up on X.

Note: This article is co-published on rombrom.com.

However, this design choice comes with a key drawback that is not found in traditional monolithic contract designs: increased gas overhead due to an additional CALL opcode when making updates to storage.

In this post, i'll discuss how I found a gas-saving technique elsewhere in the protocol by accumulating elements in an array of structs with an unknown size. Let's dive in.

During the process of creating a rental, an OrderParameters struct is received from Seaport via the Create Policy and must be persisted in contract storage. This is so that the rental order can eventually be stopped. While the Create Policy processes this data, it must be able to know which items in a Seaport order are considered rentals and which are considered payments.

To demonstrate, I'll first show the OrderParameters struct in a Seaport order:

struct OrderParameters {
    address offerer;
    address zone;
    OfferItem[] offer;
    ConsiderationItem[] consideration;
    OrderType orderType;
    uint256 startTime;
    uint256 endTime;
    bytes32 zoneHash;
    uint256 salt;
    bytes32 conduitKey;
    uint256 totalOriginalConsiderationItems;
}

An issue arises here because there exists an OfferItem array and a ConsiderationItem array which must be filtered into two separate arrays: one consisting of ERC721/ERC1155 rental items and one consisting of ERC20 payment items.

If we were using any other language, this would be easy. A single array could be filtered into two smaller arrays. Solidity, however, does not yet have support for dynamic memory arrays. So its not possible to use a struct array without first knowing how large the array will become.

To solve for this, I implemented the Accumulator Package which can dynamically allocate structs in-memory using a custom intermediate array encoding. Then, when needed, it can be converted back into the standard Solidity array type since now we know the complete size of the data.

As I stated before, the processing of creating a rental involves converting the OfferItem and ConsiderationItem arrays into buckets of rentals and payments. Before we get to this step, all the items in the Seaport order are first coalesced into one single Item array.

This process is done via _convertToItems in the Create Policy. You can view the source code here.

This conversion was used to make the data types easier to work with by providing a more general implementation that encapsulates both OfferItem and ConsiderationItem structs.

Here's how it looks:

struct Item {
    ItemType itemType;
    SettleTo settleTo;
    address token;
    uint256 amount;
    uint256 identifier;
}

With an Item array fully built up, the next step is to pick out the rental items (ERC721 and ERC1155 tokens) and build up a new array which can be sent over to the Storage Module all in one batch.

To do this, the protocol invokes the Accumulator Package's _insert function:

// Create an accumulator which will hold all of the rental asset updates, 
// consisting of IDs and the rented amount. From this point on, new memory 
// cannot be safely allocated until the accumulator no longer needs to include elements.
bytes memory rentalAssetUpdates = new bytes(0);

// Check if each item is a rental. If so, then generate the rental asset update.
// Memory will become safe again after this block.
for (uint256 i; i < items.length; ++i) {
    if (items[i].isRental()) {
        // Insert the rental asset update into the dynamic array.
        _insert(
            rentalAssetUpdates,
            items[i].toRentalId(payload.fulfillment.recipient),
            items[i].amount
        );
    }
}

// ... arbitrary logic executes here

// Add rentals to storage before any other processing
STORE.addRentals(orderHash, _convertToStatic(rentalAssetUpdates));

We start by instantiating a strip of bytes in memory called rentalAssetUpdates. This will contain an append-only encoding of the rental assets.

Since the accumulator requires a custom memory encoding, it will be manually altering the Solidity free memory pointer. Because of this, no new memory can be allocated automatically by Solidity until the accumulator has finished writing to memory.

Once the accumulator has completed writing to memory, the Solidity free memory pointer can be incremented automatically as usual.

Finally, the rentalAssetUpdate bytes variables is directly converted into a standard Solidity struct array so that it can be sent to the Storage Module.

This is a lot to unpack, so let's first turn to how the _insert function is implemented.

At a high level, the _insert function will take a bytes value (the accumulation) and continually append elements to it until it is done accumulating data. This can be considered the intermediate representation of a Solidity RentalAssetUpdate[] array.

Each time _insert is called, it will append a new series of bytes data to the current accumulator in a specific encoding. The definition of the accumulator encoding can be summed up as follows:

[0x00:0x20]: Length of the intermediate representation bytes data, in bytes
[0x20:0x40]: Number of `RentalAssetUpdate` elements stored
[0x40:0x60]: `rentalId` of the first element
[0x60:0x80]: `amount` of the first element
[0x80:0xa0]: `rentalId` of the second element
[0xa0:0xc0]: `amount` of the second element
[0xc0:0xe0]: ...

We can start with the definition for _insert. It accepts the bytes accumulator which contains all the elements that been accumulated so far in the encoding mentioned above. It also accepts a bytes32 and uint256 which make up a RentalAssetUpdate struct.

function _insert(
    bytes memory rentalAssets,
    bytes32 rentalId,
    uint256 rentalAssetAmount
) internal pure {
    // ... logic goes here
}

As an initial check, the function decides if rentalAssets has no length. If it's empty, then it is given an initial length of 32 bytes along with a single zeroed-out 32 byte element which is added to the rentalAssets value.

This code block will only execute when rentalAssets is empty so that it can be prepared to accumulate elements.

assembly {
    // This is the first time inserting into this bytes data.
    if eq(mload(rentalAssets), 0) {
        // Create some space for the initial element length word.
        mstore(rentalAssets, 0x20)

        // Zero out the number of elements.
        mstore(add(0x20, rentalAssets), 0x00)
    }
}

At this point, the memory encoding of the rentalAssets would look like this:

[0x00:0x20]: 0x0000000000000000000000000000000000000000000000000000000000000020
[0x20:0x40]: 0x0000000000000000000000000000000000000000000000000000000000000000

Next, we can turn to the logic that will execute each time _insert is called.

A RentalAssetUpdate struct has a total length of 64 bytes (or 0x40). So, on a call to _insert, the total length of the rentalAssets bytes data must increase by 0x40, along with incrementing the total number of elements being held within rentalAssets.

// ... logic previously

// Calculate the new size of the bytes data by adding
// the size of a `RentalAssetUpdate` struct.
let newByteDataSize := add(mload(rentalAssets), 0x40)

// Get the pointer for where the element data begins.
let rentalAssetElementPtr := add(rentalAssets, 0x20)

// Increase the number of rental elements by one.
let elements := add(mload(rentalAssetElementPtr), 1)

Once we know how many elements will now be contained within rentalAssets, we need to calculate the exact offset for the new RentalAssetUpdate struct. By multiplying the total number of elements contained in the bytes data by 0x40, we can calculate where to place the new element:

// Calculate the position for the new rental ID.
// To do this, calculate the total length of the element portion, then
// subtract by the initial offset. In this case, the offset is the 32-byte
// word (0x20) which contains the length of the array.
let newItemPosition := add(
    rentalAssetElementPtr,
    sub(mul(elements, 0x40), 0x20)
)

With all calculations completed, all that needs to be done is to store the newly calculated values into memory:

// Store the new byte data size
mstore(rentalAssets, newByteDataSize)

// Store the new number of elements
mstore(rentalAssetElementPtr, elements)

// Store the rental ID
mstore(newItemPosition, _rentalId)

// Store the amount in the adjacent 32-byte word
mstore(add(newItemPosition, 0x20), rentalAssetAmount)

Finally, update the Solidity free memory pointer manually so that once we are done accumulating, we can hand memory management back to Solidity automatically:

// Update the free memory pointer so that memory is safe
// once we stop doing dynamic memory array inserts
mstore(0x40, add(newItemPosition, 0x40))

And that's it! There's nothing to return since all updates were made directly in memory. The next few sections will focus on how this intermediate encoding can be used to get the data back into an array encoding that Solidity can naturally parse.

Recall the function call to the Storage Module that contains all the rentals that were provided by the Item array:

// Add rentals to storage before any other processing
STORE.addRentals(orderHash, _convertToStatic(rentalAssetUpdates));

We can now look at how the custom encoding of rentals can be converted back into a standard Solidity array with a type of RentalAssetUpdate[]. But first, it's worth going over how standard Solidity arrays are stored in memory.

Solidity memory allocation for arrays is not well-documented since it follows a different encoding than what is found in the Contract ABI Specification. So for the most part, we'll be flying on our own here.

Lets first take a look at the default memory layout before any memory has been allocated so that we can get our bearings. We can do this using Chisel, with its !memdump and !stackdump commands. By running !memdump, we can see the initialized memory that all Solidity function calls begin with:

[0x00:0x20]: 0x0000000000000000000000000000000000000000000000000000000000000000
[0x20:0x40]: 0x0000000000000000000000000000000000000000000000000000000000000000
[0x40:0x60]: 0x0000000000000000000000000000000000000000000000000000000000000080
[0x60:0x80]: 0x0000000000000000000000000000000000000000000000000000000000000000

According to the memory layout docs, the slot definitions are as follows:

• 0x00 - 0x3f (64 bytes): scratch space for hashing methods

• 0x40 - 0x5f (32 bytes): currently allocated memory size (aka. free memory pointer)

• 0x60 - 0x7f (32 bytes): zero slot - this is used as an initial pointer value for memory arrays that have not been initialized with a size yet

We can see how the zero slot is utilized once we declare an empty RentalAssetUpdate array in Chisel:

RentalAssetUpdate[] memory assets;

Now, if we were to peek at our stack with !stackdump, we would see this element on top:

[0]: 0x0000000000000000000000000000000000000000000000000000000000000060
[1]: ...
[2]: ...

This indicates that the assets variable is pointing to address 0x60 in memory, which is the zero slot. To see how this changes, we'll instantiate our array next:

assets = new RentalAssetUpdate[](2);

First, let's take a look at the stack to see if anything is different:

[0]: 0x0000000000000000000000000000000000000000000000000000000000000080
[1]: ...
[2]: ...

Interestingly, the element pointing to the assets variable has now changed from 0x60 to 0x80. Let's !memdump the memory so we can see what's going on:

[0x00:0x20]:   0x0000000000000000000000000000000000000000000000000000000000000000
[0x20:0x40]:   0x0000000000000000000000000000000000000000000000000000000000000000
[0x40:0x60]:   0x0000000000000000000000000000000000000000000000000000000000000160
[0x60:0x80]:   0x0000000000000000000000000000000000000000000000000000000000000000
---------------------------------------------------------------------------------
[0x80:0xa0]:   0x0000000000000000000000000000000000000000000000000000000000000002
[0xa0:0xc0]:   0x00000000000000000000000000000000000000000000000000000000000000e0
[0xc0:0xe0]:   0x0000000000000000000000000000000000000000000000000000000000000120
---------------------------------------------------------------------------------
[0xe0:0x100]:  0x0000000000000000000000000000000000000000000000000000000000000000
[0x100:0x120]: 0x0000000000000000000000000000000000000000000000000000000000000000
[0x120:0x140]: 0x0000000000000000000000000000000000000000000000000000000000000000
[0x140:0x160]: 0x0000000000000000000000000000000000000000000000000000000000000000

We can see that a whole bunch of things have changed. I've added in lines so that its easier to view the clear segments of the memory.

In location 0x40, you'll notice that the free memory pointer was updated to 0x160. This intuitively makes sense because we have allocated memory so far up to address 0x160.

Lets turn to location 0x80 which is where the assets variable is now pointing to. You'll see that the value stored there is 0x02. This value defines the length of the array.

After the length definition, you'll see two pointers located at 0xa0 and 0xc0 which contain the values 0xe0 and 0x120, respectively. These are considered the head values of the array, and are locations that contain pointers in memory to the actual location of where the data is stored. Recall that each RentalAssetUpdate contains a bytes32 and a uint256, totaling 64 bytes. We can do the math here and see that the difference between 0x120 and 0xe0 is 0x40, or 64 bytes.

Looking at location 0xe0, we can see that it contains an empty word, followed by another empty word. This is the same case at location 0x120. These are spots in memory which have been reserved but not allocated to just yet. These are considered the tail values in the array and contain the actual data of the elements being stored in the array. We'll see how those get populated once we add some elements to the assets array. Lets do that now:

assets[0] = RentalAssetUpdate(bytes32(uint256(5)), uint256(6));

We can now !memdump the memory again to see what changed:

[0x00:0x20]:   0x0000000000000000000000000000000000000000000000000000000000000000
[0x20:0x40]:   0x0000000000000000000000000000000000000000000000000000000000000000
[0x40:0x60]:   0x00000000000000000000000000000000000000000000000000000000000001a0
[0x60:0x80]:   0x0000000000000000000000000000000000000000000000000000000000000000
---------------------------------------------------------------------------------
[0x80:0xa0]:   0x0000000000000000000000000000000000000000000000000000000000000002
[0xa0:0xc0]:   0x0000000000000000000000000000000000000000000000000000000000000160
[0xc0:0xe0]:   0x0000000000000000000000000000000000000000000000000000000000000120
---------------------------------------------------------------------------------
[0xe0:0x100]:  0x0000000000000000000000000000000000000000000000000000000000000000
[0x100:0x120]: 0x0000000000000000000000000000000000000000000000000000000000000000
[0x120:0x140]: 0x0000000000000000000000000000000000000000000000000000000000000000
[0x140:0x160]: 0x0000000000000000000000000000000000000000000000000000000000000000
---------------------------------------------------------------------------------
[0x160:0x180]: 0x0000000000000000000000000000000000000000000000000000000000000005
[0x180:0x1a0]: 0x0000000000000000000000000000000000000000000000000000000000000006

This is a bit unexpected. The zero values located at memory regions 0xe0 and 0x120 were not updated. They were completely left alone. Instead a RentalAssetUpdate element was added starting at location 0x160. We can verify that this is indeed what happened because we can look to the head of the array and see that in location 0xa0, it switched from holding a value of 0xe0 to now have a value of 0x160. It's also worth noting that since the second element in the array is still unallocated, location 0xc0 remains pointing to the zero value located at 0x120.

Let's try adding one more element to the array to see if a pattern emerges:

assets[1] = RentalAssetUpdate(bytes32(uint256(7)), uint256(8));

Now, dumping the memory we get:

[0x00:0x20]:   0x0000000000000000000000000000000000000000000000000000000000000000
[0x20:0x40]:   0x0000000000000000000000000000000000000000000000000000000000000000
[0x40:0x60]:   0x00000000000000000000000000000000000000000000000000000000000001e0
[0x60:0x80]:   0x0000000000000000000000000000000000000000000000000000000000000000
---------------------------------------------------------------------------------
[0x80:0xa0]:   0x0000000000000000000000000000000000000000000000000000000000000002
[0xa0:0xc0]:   0x0000000000000000000000000000000000000000000000000000000000000160
[0xc0:0xe0]:   0x00000000000000000000000000000000000000000000000000000000000001a0
---------------------------------------------------------------------------------
[0xe0:0x100]:  0x0000000000000000000000000000000000000000000000000000000000000000
[0x100:0x120]: 0x0000000000000000000000000000000000000000000000000000000000000000
[0x120:0x140]: 0x0000000000000000000000000000000000000000000000000000000000000000
[0x140:0x160]: 0x0000000000000000000000000000000000000000000000000000000000000000
---------------------------------------------------------------------------------
[0x160:0x180]: 0x0000000000000000000000000000000000000000000000000000000000000005
[0x180:0x1a0]: 0x0000000000000000000000000000000000000000000000000000000000000006
[0x1a0:0x1c0]: 0x0000000000000000000000000000000000000000000000000000000000000007
[0x1c0:0x1e0]: 0x0000000000000000000000000000000000000000000000000000000000000008

Interesting. This time it allocated the new element exactly where it should have gone, which is directly after element 0 in the array. Its also worth mentioning that the head pointer for element 1, located at 0xc0, is now pointing away from the zero value stored at 0x120, and toward the actual data that we stored, which starts at 0x1a0.

So what are these 4 consecutive zero words doing in memory from 0xe0 to 0x140? These regions seem to be used as scratch space for each element for some operations in Solidity. The most clarity that be found is located in the Layout in Memory section of the Solidity documentation that reads:

There are some operations in Solidity that need a temporary memory area larger than 64 bytes and therefore will not fit into the scratch space. They will be placed where the free memory points to, but given their short lifetime, the pointer is not updated. The memory may or may not be zeroed out. Because of this, one should not expect the free memory to point to zeroed out memory.

Because of situations like this where definitions of the Solidity memory layout are a bit vague, I felt that it was safer to design an intermediate encoding of an array and then manually convert it back to a Solidity array rather than attempting to mimic Solidity's process of memory management.

We can now turn to how I implemented this conversion from the intermediate encoding into a standard Solidity memory array.

Now armed with the knowledge of how Solidity Struct arrays are encoded, it should be a breeze to cover how we convert the custom intermediate representation back into a Solidity array.

We'll start with the definition of _convertToStatic. It accepts only the intermediate encoded rentalAssetUpdates parameter and returns a native Solidity RentalAssetUpdate[] array.

function _convertToStatic(
    bytes memory rentalAssetUpdates
) internal pure returns (RentalAssetUpdate[] memory updates) {
    // ... logic continues on 
}

For this implementation, there is a hybrid Solidity/Yul approach to extract the values. The return values are defined in solidity, but the extraction of the elements are defined using Yul.

The conversion begins by getting pointers to the start of the encoded elements and the total number of elements in the encoding. Then, the Solidity RentalAssetUpdate[] array can be instantiated with the exact number of elements specified in the encoding:

// Pointer to the rental asset update data.
bytes32 rentalAssetUpdatePointer;

// Load the length of the rental asset update items.
uint256 rentalAssetUpdateLength;
assembly {
    // Get a pointer to the number of elements in the bytes data.
    // With the 0x20 offset, we would be loading the length of the entire
    // byte string, but we want the element length which starts one
    // word to the right.
    rentalAssetUpdatePointer := add(0x20, rentalAssetUpdates)

    // Load the number of elements.
    rentalAssetUpdateLength := mload(rentalAssetUpdatePointer)
}

// Instantiate the update array.
updates = new RentalAssetUpdate[](rentalAssetUpdateLength);

From here, each element is looped through by calculating its offset in memory since we know that each RentalAssetUpdate struct is exactly 0x40 bytes long.

// Iterate through each item in the byte data, and add it as
// an entry to the array.
for (uint256 i = 0; i < rentalAssetUpdateLength; ++i) {
    // Define the placeholders.
    RentalId rentalId;
    uint256 amount;

    // Extract the current element from the byte data.
    assembly {
        // Determine element offset by multiplying the length of a
        // RentalAssetUpdate struct (0x40) by the current index, then
        // add a word to make sure the next word is accessed because the
        // offset defaults to being set to the length pointer.
        let currentElementOffset := add(0x20, mul(i, 0x40))

        // Load the rental ID starting at the data pointer.
        rentalId := mload(add(rentalAssetUpdatePointer, currentElementOffset))

        // Load the amount at the data pointer adjacent to it.
        amount := mload(
            add(0x20, add(rentalAssetUpdatePointer, currentElementOffset))
        )
    }

    // Set the items
    updates[i] = RentalAssetUpdate(rentalId, amount);
}

Once the loop completes, the updates array can be returned and used as normal in other areas of the Solidity code.

At its core, the Accumulator is a technique that takes a number of elements in Solidity and can append them to an array of unknown sizing. This package fills a wide gap in the Solidity language since there still doesn't exist a way to work with dynamically allocated arrays in memory.

I would not have been able to create this implementation without a heavy reliance on one of my favorite tools, Chisel. I encourage you to use Chisel with the examples in this post to see how Solidity allocates array memory for yourself.

You can view the implementation of the Accumulator Package here, and if you have any further questions on how the accumulator works, feel free to reach out to myself at alec@021.gg or on x.com.

There is no one design that works best for a smart contract protocol. For Endgame, I had a few considerations in mind before any actual code was written.

Knowing that the protocol would have to integrate with both Seaport and Safe smart contracts, I wanted a design that would reduce the surface area for bugs as much as possible, given the difficulty of testing a protocol that integrates with another. For me, this meant a few things: an airtight admin privilege design, well-divided contracts each with as few responsibilities as possible, and writing well-commented code.

Additionally, as with any protocol, it was hard to tell how Endgame was going to evolve over time. Given that smart contracts can't be afforded the rapid release cycles than an API or a front-end can, it was important that the protocol architecture be flexible and modular.

Finally, a given requirement was that the protocol would be deployed to ETH mainnet. This meant the protocol would have to be considerate of gas consumption so as to not price-out users from interacting with the protocol due to excessive gas costs.

I found everything I was looking for, and then some, in the Default Framework design. This protocol architecture sets itself apart by shifting the focus of a protocol away from organizing contracts around processes, and toward organizing contracts around data models.

As stated in the Default Framework repository, the goal is to take a protocol from looking something like this:

and turn it into something to like this:

The key change needed to design protocol like this revolves around the idea that some contracts should be external-facing (stateless policies) and some should be internal-facing (stateful modules).

This design limits the maximum number of nested dependencies for a contract to 1 while also providing guarantees on which contracts are allowed to modify specific storage.

I won't go over all the details of the Default Framework here but for more information, you can read about it on their Github. For the rest of this post, I will be covering how the Endgame architecture was designed while using this framework as a guide.

The Kernel is a contract whose responsibility is to orchestrate the interaction between user-facing policy contracts and stateful module contracts. It maintains the bookkeeping needed to ensure that modules can only be accessed by registered policies. Additionally, the Kernel will manage admin roles for operations such as adding and removing policies or modules from the protocol.

The key portion of the kernel's administrative logic lies within the permissioned modifier.

modifier permissioned() {
    if (!kernel.modulePermissions(KEYCODE(), Policy(msg.sender), msg.sig)) {
        revert Errors.Module_PolicyNotAuthorized(msg.sender);
    }
    _;
}

The Kernel keeps track of each module using a unique key-code assigned to it. Using this key-code, it can check if the msg.sender has previously registered with the protocol in relation to the function selector that it is trying to access. This process is the key to maintaining the separation of business logic and contract storage. As such, each function that modifies storage on a module must implement this modifier to function properly.

Modules are considered the "back-end" of the protocol. They hold the global storage of the protocol and cannot be directly interacted with by any EOA or contract outside of the protocol itself. For any contract to be allowed to modify storage on a module, they must be explicitly allowed to access a particular function selector on the module. This design makes storage access an opt-in feature, and prevents any unintended side-effect where contracts can modify storage that was unintended.

Endgame uses two modules: a Storage Module which contains data relating to rentals that are active in the protocol, and an Escrow Module which holds ERC20 token payments until they are ready to be collected.

For example, a function on the Storage Module looks like this:

function addRentals(
    bytes32 orderHash,
    RentalAssetUpdate[] memory rentalAssetUpdates
) external onlyByProxy permissioned {
    // ... logic goes here
}

As stated before, each function that modifies storage on the module will have a permissioned modifier. This modifier makes a call to the kernel to see if the address calling this function has registered its intent with the protocol to add rentals to storage.

Policies are user-facing contracts which do not maintain storage of their own. Their main purpose is to act as windows into the protocol. For example, to create a rental with Endgame, a user would interact with the Create Policy. In reality, it's a bit more complicated than that since Seaport is the entity that interacts with the Create policy but the idea is the same. For stopping a rental, the user interacts with the Stop Policy. For changes to the protocol itself such as adding or removing another policy, the user would interact with the Admin policy (if they are an admin, of course).

A key benefit here is the ability to slice up the protocol into clear sections of business logic. The Stop Policy is not concerned with how the Create Policy operates, and vice-versa. They each only care about interfacing with the data models that are needed to carry about their own policy business logic.

We can now turn to how a policy interacts with a module contract. We have seen that a state-modifying module function cannot be accessed unless the caller has previously registered with the kernel about the function selectors it intends to use. So, how does a policy contract register its intent?

Continuing our example from before, we can show how the Create Policy intends to update protocol storage about new rentals that have been processed.

/**
 * @notice Upon policy activation, permissions are requested from the kernel to access
 *         particular keycode <> function selector pairs. Once these permissions are
 *         granted, they do not change and can only be revoked when the policy is
 *         deactivated by the kernel.
 *
 * @return requests Array of keycode <> function selector pairs which represent
 *                  permissions for the policy.
 */
function requestPermissions()
    external
    view
    override
    onlyKernel
    returns (Permissions[] memory requests)
{
    requests = new Permissions[](2);
    requests[0] = Permissions(toKeycode("STORE"), STORE.addRentals.selector);
    // ... requests continue on 
}

Each policy contract inherits an abstract Policy class and must implement the requestPermissions function if it wishes to modify protocol storage. An array of permissions is built up which specifies the key-code of the module contract and the function selector to access.

When a new policy is added to the protocol, the Kernel will execute requestPermissions on the policy and store the permissions which will be used in the future when validating calls from the policy to a module.

By splitting up the protocol business logic into their own policy contracts, it's inevitable that at some point the policy contracts would want to share logic or access the same helper functions.

For this, the protocol utilizes a series of packages. Succinctly put, these are sharable and inheritable abstract contracts with immutable state that can enhance the functionality of a policy contract.

For example, the Signer Package contains logic related to signed payloads and signature verification when creating or stopping rentals. The functions in this package are needed by both the Create Policy and the Stop Policy, so rather than duplicate the functionality, each policy can inherit this package contract and use its functions that way.

Putting all the data in contract storage needed to keep track of a single rental is not cheap. Each token involved in the order, all its hook data, and then the rental metadata itself need to be tracked. It would take up a lot of storage slots to store a single RentalOrder struct:

struct RentalOrder {
    bytes32 seaportOrderHash;
    Item[] items;
    Hook[] hooks;
    OrderType orderType;
    address lender;
    address renter;
    address rentalWallet;
    uint256 startTimestamp;
    uint256 endTimestamp;
}

// A rental order has an array of hooks
struct Hook {
    // The hook contract.
    address target;
    // Index of the item in the order to apply the hook to.
    uint256 itemIndex;
    // Any extra data that the hook will need.
    bytes extraData;
}
 
// A rental order has an array of items
struct Item {
    ItemType itemType;
    SettleTo settleTo;
    address token;
    uint256 amount;
    uint256 identifier;
}

Thats a lot of SSTOREs!

To avoid all this overhead when it comes to storing rental data, the protocol opts for hashing the RentalOrder struct and storing that instead. This brings the cost of storing a rental order down to a single SSTORE.

As with any design, there are always trade-offs. The issue this brings is that by storing the hash, you lose access to the data that the rental order was supposed to store in the first place. To remedy this, upon each rental the protocol will emit a RentalOrderStarted event with all the data necessary to reconstruct a RentalOrder. That way, the data doesn't need to be put in protocol storage but can still be accessible.

event RentalOrderStarted(
    bytes32 orderHash,
    bytes emittedExtraData,
    bytes32 seaportOrderHash,
    Item[] items,
    Hook[] hooks,
    OrderType orderType,
    address indexed lender,
    address indexed renter,
    address rentalWallet,
    uint256 startTimestamp,
    uint256 endTimestamp
);

Having now gone through an audit using Code4rena, I feel confident that the data model methodology for designing a smart contract protocol was the correct approach to take.

During our audit, there wasn't a single reported issue related to execution of an unauthorized function because of some misconfiguration of admin privileges. Additionally, the design lends itself to being highly configurable, able to adapt to any new contracts that we may want to fold into the protocol later on.

Endgame is still in its early stages, and I am excited to see how the protocol evolves from here. You can view the implementation of the protocol here, and if you have any questions on the protocol architecture, feel free to reach out to myself at alec@021.gg or on x.com.

I think I understand the perceived importance of structuring upfront. As humans we like patterns, structure and the clarity these things provide. "If I think really really hard about how my project needs to be structured up front, I'll win back velocity once I'll actually start coding because I won't have to think about where to place things."

Structuring a project upfront is a fantastically useless navel-gazing distraction. It distracts you from the actual work with its feigned importance. It's a very inconspicuous form premature optimization and, quite frankly, busywork. What's more, structuring upfront runs directly counter to coding's actual craft and distances you from the material and landscape. The map is not the territory.

Just get started. Do the work.

Oooh, onions! We're definitely cookin'.

There's no shortage of metaphors when it comes to coding. One of the most long-lived ones is the tiered "onion" architecture. Like an onion, it has a core being enveloped by other layers with differing responsibilities. The three tier architecture being a prime example. It separates presentation, application (logic) and data into separate layers. Data placed firmly at the core, enveloped by the application layer, enveloped by the presentation layer.

Let me cycle back to how we swapped the engine at 2/3rd of the project. The primary reason we were confident about swapping Next.js with Remix is because we were quite diligent in keeping apart the architectural layers of our front end. These layers do not corroborate 1-on-1 to three tier architecture. We're dealing with a front end here and not a complete stack. Still, the principle of layering can be applied somewhat recursively to fit this slice of our stack.

Roughly speaking we discern the following:

1. Service layer, consisting of configuration, API interfacing, chain & wallet interfacing, and rental protocol interfacing.

2. User Interface and Browser/React utilities.

3. Engine, providing SSR and route endpoints.

Now, these layers do not necessarily correlate with our module structure. Generally speaking though, each layer can consume any preceding layer. Notice how the engine is an outer layer. Our core user interface components are separate from it, as is our core logic and service interfacing. The engine mostly provides an harness to fit our core logic and UI onto. It provides ways to expose our user interface through routes and ways to optimize initial data fetching to get those fast initial renders.

There are some parts which remain somewhat tightly coupled, because they're pretty much dependent on engine specifics. This makes them inherently hard to decouple. Take cookies and sessions for example. Next.js and Remix both provide APIs to handle these. There's some overlap but consuming cookies (ha!) generally wasn't worth abstracting. In these cases we do try to keep data model and consumers of cookie data in our service and UI layers.

If there's anything to take away from this section, it's that having a clear idea about layering responsibilities will guide decisions on structure and organization.

So far I've been all talk. It's high time for some actual code. Lets implement the way we fetch data with Tanstack Query.

Note: there is a demo repository you can check out which contains all code below.

# Create a Remix project, install Tanstack Query
# and run dev server

npx create-remix@latest remix-tanstack-query
cd remix-tanstack-query
npm i --save-exact @tanstack/react-query
npm run dev

Lets do some scaffolding first. We need some fake data to fetch. We'll simulate this as well as possible network latency and error cases.

// File: app/getData.ts

export async function getData() {
  const num = Math.random();
  await new Promise((ok) => setTimeout(ok, 1000 * num));
  if (num > 0.5) throw new Error(`Bad number: ${num}`);
  return `Good number: ${num}`;
}

We also need to add a <QueryClientProvider /> to our root layout.

// File: app/root.tsx

import {
  QueryClient,
  QueryClientProvider
} from '@tanstack/react-query';
import { useState } from 'react';
// ...
export function Layout({ children }: { children: React.ReactNode }) {
  // The reason we want to initialze `QueryClient` in a state
  // is because we need the client to be unique for each user.
  const [queryClient] = useState(
    new QueryClient({
      defaultOptions: {
        // No retries in testing, else we'll never see errors.
        queries: { retry: false },
      },
    })
  );
  // ...

  return (
    // ...
        <QueryClientProvider client={queryClient}>
          {children}
        </QueryClientProvider>
    // ...
  );
}
// ...

Lastly, lets implement this in our app/routes/_index.tsx route.

// File: app/routes/_index.tsx
// ...
import { useQuery } from '@tanstack/react-query';
import { getData } from '~/getData';
// ...
export default function Index() {
  const { data, error, isLoading } = useQuery({
    queryFn: () => getData(),
    queryKey: ['num'],
  });

  return (
    <div
      style={{
        color: isLoading ? 'blue' : error ? 'red' : 'green',
        fontFamily: 'system-ui, sans-serif',
        lineHeight: '1.8',
      }}
    >
      <p>Data: {data}</p>
      <p>Error: {error?.message}</p>
    </div>
  );
}

Big whoop. This is Tanstack Query 101. Lets get that SSR going. Tanstack Query offers some flexibility here. The initialState parameter on useQuery and friends could be used but will lead to prop drilling. The most robust and portable method is leveraging its HydrationBoundary and dehyrate() APIs. You can implement these per route, but Remix allows you to write even less boilerplate.

When you visit a route on Remix, it will fetch data from all loaders in the route cascade. If you pair this with Remix's powerful useMatches [1] hook, you can combine dehydrated data from all matching loaders without having to resort to nested HydrationBoundary components. The only requirement is introducing a convention on how (prefetched) loader data is returned. So lets agree here and now that any loader returning JSON which includes a dehydratedState property has state we want to accumulate.

// File: app/useMatches.ts

import { useMatches } from '@remix-run/react';
import type { DehydratedState } from '@tanstack/react-query';

export function useDehydratedState() {
  const matches = useMatches();
  return (
    matches
      // @ts-expect-error in all cases the following will resolve
      // to undefined if `dehydratedState` isn't available.
      .flatMap(({ data }) => (data?.dehydratedState as DehydratedState) ?? [])
      .reduce<DehydratedState>(
        (result, current) => ({
          queries: [...result.queries, ...current.queries],
          mutations: [...result.mutations, ...current.mutations],
        }),
        { queries: [], mutations: [] }
      )
  );
}

Now lets add the hydration setup to our root layout. Also note the addition of staleTime to our client side QueryClient. Our dehydrated client already fetched and without adding at least a bit of staleTime, our queries would be executed again on the client.

// File: app/root.tsx

import {
  HydrationBoundary,
  QueryClient,
  QueryClientProvider
} from '@tanstack/react-query';
import { useState } from 'react';
import { useDehydratedState } from './useDehydratedState';
// ...
export function Layout({ children }: { children: React.ReactNode }) {
  // The reason we want to initialze `QueryClient` in a state
  // is because we need the client to be unique for each user.
  const [queryClient] = useState(
    new QueryClient({
      defaultOptions: {
        // No retries in testing, else we'll never see errors.
        queries: { retry: false },
        staleTime: 5000,
      },
    })
  );
  const dehydratedState = useDehydratedState();
  // ...

  return (
    // ...
        <HydrationBoundary state={dehydratedState}>
          <QueryClientProvider client={queryClient}>
            {children}
          </QueryClientProvider>
        </HydrationBoundary>
    // ...
  );
}
// ...

And hook up a loader, making use of dehydrate(), to the index route.

// File: app/routes/_index.tsx
import { json, type LoaderFunction, type MetaFunction } from '@remix-run/node';
import { QueryClient, dehydrate, useQuery } from '@tanstack/react-query';
import { getData } from '~/getData';

export const loader: LoaderFunction = async () => {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery({
    queryFn: () => getData(),
    queryKey: ['num'],
  });
  return json({ dehydratedState: dehydrate(queryClient) });
};
// ...

And fin.

This is basically the setup we use for anything data-fetching related. We have some modules exporting ready-to-use functions like getData() from our service layer. These are used in our UI components directly on useQuery(). Our engine also imports these so they can be hooked up easily to prefetching. This setup has been unchanged since we implemented it in Next.js. The prefetching logic, instead of being housed in a loader, was just part of a React Server Component. Moving over the logic to a loader was a breeze.

Right.

The example we worked through is a simple one. Still, it informs us about layers. The way Tanstack Query integrates naturally separates data fetching from presentation and allows you separate prefetching into a separate layer as well. I guess you could add an extra abstraction which wraps setting up and dehydrating a client, but trust me when I say the ROI isn't great. You're not swapping engines every day.

The layers in the example aren't that clearly demarcated as there's some overlap in code location. The index route, for example, contains code concerning the UI layer and the prefetching layer. Layers aren't necessarily related to code location, folders and files. It's got more to do with what responsibility and/or domain the code envelops.

The beauty of code is that it's easily rearranged. Moving the UI code into a separate component is trivial. So is moving or abstracting loader (pre)fetching. When our example application grows you could very well imagine UI components being split off into ~/components. At some point it might make sense to create a ~/loaders module which houses recurring loader patterns. getData() could grow into a slew of modules housed in ~/api. Who knows.

The key thing here is learning to recognizing these layers. And understanding—nay, grokking—that moving, abstracting, and refactoring code are inexpensive operations. Start inline and work your way outwards. The code will tell you when it needs changing.

Andy Hunt and David Thomas, authors of "The Pragmatic Programmer," quite aptly captured the meandering aspects of the craft in their garden metaphor. They recognized the paradoxical sentiments around programming. One the one hand the discourse touts coding an engineering profession: plan, execute, deliver. All according to spec. On the other hand, the act of coding itself often yields new discoveries orthogonal to the initial plan.

The garden doesn't quite come up the way you drew the picture. This plant gets a lot bigger than you thought it would. You've got to prune it. You've got to split it. You've got to move it around the garden. This big plant in the back died. You've got to dig it up and throw it into the compost pile. [2]

When we started building Endgame we didn't start with any specific structure in mind. The first commit is literally the result from npx create-next-app@latest and we cruised on this structure for our initial scaffolding. We just wrote a lot of things inline. When we added WalletConnect support about 12 commits in, the @/components folder was added. It's a central place for UI components. Initially we had everything related to our WalletConnect integration housed in @/components/wallet. Much later we had split this up into @/wallet and @/components/wallet. The former being responsible for configuration and generic initialization, the latter specifically catered to UI. When we worked on getting GraphQL interfacing set up, we added @/graphql, housing code generation artifacts from GraphQL Codegen, our GraphQL client initialization and some utilities. We shoehorned our API interfacing layer into this module which we later extracted into @/services/api. We had a @/config folder which later turned into a simpler @/config.ts file. [3]

Anyway. What I'm trying to get at is that we just started doing the work. It didn't make sense worrying about structure before we'd have a solid grasp of how the thing we were building could be best structured. We did, however, have a good sense on how to layer things. Because, frankly, this wasn't our first rodeo.

Coding is just as much a process of discovering the codified as it is codifying the discovered. One of the keys to becoming better is trying to make this feedback loop as tight as possible. Because many iterations through this loop will offset the practice more and more to codifying the discovered.

Just get started. Do the work.

1. Not related to fire starting equipment.

2. See Programming is Gardening, not Engineering: A Conversation with Andy Hunt and Dave Thomas, Part VII. Quite some concepts from The Pragmatic Programmer make the rounds here.

3. We're leveraging TypeScript's paths option as a poor-man's monorepo: @/* › src/*, ~/* › app/*. Aside from freeing us from walking up paths, it's more subtle effect is that you tend to folders in src/* and app/* as proper, separate modules.

Note: This article is co-published on rombrom.com.

In this post, I will be focusing on how we use Seaport as an order fulfillment engine so that Endgame can focus on just the rental logic. I'll walk through the process of creating, fulfilling, and stopping an order to give a full overview of how a rental flows through the protocol.

Let's get started!

All new rental orders must first be created by a lender. The lender is allowed to craft the exact terms they wish to see carried out by the order. They get to specify: items to lend, payment items to receive, any hooks that will apply to the rented items (see my post here if you are unfamiliar with hooks), and rental-specific conditions such as the duration of the rental.

To start, creating a rental order involves constructing and signing a valid Seaport order with a special data payload so that the protocol's zone contract is invoked during the order fulfillment. This step is crucial because without the zone contract, the order fulfillment would be permanent, leaving no way for the lender to get their assets back.

For each new rental order, the lender must sign a Seaport OrderComponents struct. This contains all the parameters for the Seaport order, and is completely agnostic to the fact that we will be using it for rentals.

/**
 * @dev An order contains eleven components: an offerer, a zone (or account that
 *      can cancel the order or restrict who can fulfill the order depending on
 *      the type), the order type (specifying partial fill support as well as
 *      restricted order status), the start and end time, a hash that will be
 *      provided to the zone when validating restricted orders, a salt, a key
 *      corresponding to a given conduit, a counter, and an arbitrary number of
 *      offer items that can be spent along with consideration items that must
 *      be received by their respective recipient.
 */
struct OrderComponents {
    address offerer;
    address zone;
    OfferItem[] offer;
    ConsiderationItem[] consideration;
    OrderType orderType;
    uint256 startTime;
    uint256 endTime;
    bytes32 zoneHash;
    uint256 salt;
    bytes32 conduitKey;
    uint256 counter;
}

The items to pay particular attention to are the zone and zoneHash parameters. In a traditional Seaport order, the zone parameter is typically left blank. In our case, the zone address for all rental orders is the Create Policy contract, which handles creation of rental orders.

By specifying a zone address in the OrderComponents struct, Seaport will hand the flow of execution to the zone contract after it has fulfilled the order. This is precisely the mechanism that Endgame uses to ensure that a fulfilled Seaport order is logged and processed, so that it can eventually be stopped in the future.

The zoneHash parameter is a hashed value of data that contains all of the rental terms and conditions that the lender has specified for a specific order. This data includes the type of rental order, the rental duration, and any hooks for the rentals. After this order has been signed, a counterparty (the fulfiller) will pass the unhashed data that makes up the zoneHash into a Seaport fulfillment function to prove to the protocol that both the lender and the renter of the order have agreed on the same rental terms.

A zone hash is the EIP-712 hashed version of the following struct:

/**
 * @dev Order metadata contains all the details supplied by the offerer when they 
 * 		sign an order. These items include the type of rental order, how long the 
 * 		rental will be active, any hooks associated with the order, and any data that 
 * 		should be emitted when the rental starts.
 */
struct OrderMetadata {
    // Type of order being created.
    OrderType orderType;
    // Duration of the rental in seconds.
    uint256 rentDuration;
    // Hooks that will act as middleware for the items in the order.
    Hook[] hooks;
    // Any extra data to be emitted upon order fulfillment.
    bytes emittedExtraData;
}

A bit of information about each parameter in the OrderMetadata struct:

• orderType: When a lender wants to create a rental, they must choose an order type. There are three order types supported by the protocol, but only 2 are external and can be used by lenders.

  • BASE: This order type describes a rental order in which the lender will construct a seaport order that contains at least one ERC721 or ERC1155 offer item, and at least one ERC20 consideration item. A lender would choose this order when they want to be paid by a renter in exchange for lending out their asset(s) for a specific amount of time.

  • PAY: This order type describes an order in which the lender wishes to pay the renter for renting out their asset. This order must contain at least one ERC721 or ERC1155 offer item and at least one ERC20 offer item. It must contain 0 consideration items. This may sound counter-intuitive but the rationale is that some lenders may get benefit (tokens, rewards, etc) from allowing others to interact with contracts (on-chain games, etc) with their assets to extract some type of value from the lended asset.

  • PAYEE: This order type cannot be specified by a lender and should result in a revert if specified. PAYEE orders act as mirror images of a PAY order, and they are used by the protocol to match them up with PAY orders. In other words, a PAYEE order has 0 offer items, and should specify the offer items of the target PAY order as its own consideration items, with the proper recipient addresses.

• rentDuration: The total duration of the rental in seconds.

• hooks: The hooks which will be specified for the rental.

• emittedExtraData: This is any extra data that the lender wishes to emit once a rental has been fulfilled. This can be useful for integrations with Endgame that occur off-chain.

After the OrderMetadata has been constructed, its hash can be constructed using a convenience function which exists on the Create Policy. This will then be the value that is used for the zoneHash.

/**
 * @notice Derives the order metadata EIP-712 compliant hash from an `OrderMetadata`.
 *
 * @param metadata Order metadata converted to a hash.
 */
function getOrderMetadataHash(
    OrderMetadata memory metadata
) external view returns (bytes32) {
    return _deriveOrderMetadataHash(metadata);
}

To see how an OrderMetadata struct is converted into a EIP-712 typehash, check out _deriveOrderMetadataHash in the Signer Package.

Next, the OrderComponents struct can be hashed and then signed by the lender. This happens off-chain but you can see how its done using our test engine:

// generate the order hash
orderHash = seaport.getOrderHash(orderComponents);

// generate the signature for the order components
bytes memory signature = _signSeaportOrder(_offerer.privateKey, orderHash);

With the signature and the OrderComponents generated, they can be combined into a Seaport Order struct which will be used to fulfill the order.

/**
 * @dev Orders require a signature in addition to the other order parameters.
 */
struct Order {
    OrderParameters parameters;
    bytes signature;
}

Before an order can be fulfilled, it must first be submitted to the Endgame backend to receive a signature from the protocol signer. The protocol signer is an EOA managed by 021 which will tell the protocol if an order is still fulfillable. Without this signature, the order will be considered invalid to fulfill.

Some responsibilities of the protocol signer include:

• Signing off on orders that have not been canceled.

• Ensuring the wallet address that requested the fulfillment is the actual address which will execute the fulfillment.

• Tying together the rental order with the correct OrderMetadata struct.

The protocol signer will generate a signature from a RentPayload struct by invoking getRentPayloadHash on the Create Policy contract.

A RentPayload struct looks like this:

struct RentPayload {
    // Hash of the order being fulfilled
    bytes32 orderHash; 
    // contains the rental wallet address that will receive the rented assets 
    OrderFulfillment fulfillment;
    // Metadata of the order to fulfill.
    OrderMetadata metadata;
    // Timestamp that the protocol signer's signature will expire
    uint256 expiration;
    // EOA expected to initiate the order fulfillment
    address intendedFulfiller;
}

With a RentPayload struct acquired, along with a properly constructed and signed Seaport Order, we can invoke one of Seaport's fulfillment functions to process a signed order.

Signed orders can be fulfilled by the protocol in a few ways depending on how many orders are being filled at once, and what type of orders are being fulfilled. All Seaport fulfillment functions can be found here, but the ones specifically used by the protocol include:

• fulfillAdvancedOrder

• fulfillAvailableAdvancedOrders

• matchAdvancedOrders

For the purposes of this post, I will show the fulfillment of a single order using fulfillAdvancedOrder, but example usage for all of these fulfillment methods can be found in the protocol test engine code here.

To use fulfillAdvancedOrder, an AdvancedOrder struct must be created from a standard Seaport Order struct:

struct AdvancedOrder {
    // Order parameters that were signed
    OrderParameters parameters;
    // Don't worry about this
    uint120 numerator;
    // Don't worry about this
    uint120 denominator;
    // Signature of the order parameters
    bytes signature;
    // This data will be passed to the zone contract
    bytes extraData;
}

For the extraData field, it is constructed as a concatenation of the RentPayload struct and the signature of that struct from the protocol signer:

bytes memory extraData = abi.encode(rentPayload, rentPayloadSignature);

With the AdvancedOrder created, we now have everything we need to fulfill the order and create a rental:

seaport.fulfillAdvancedOrder(
    advancedOrder,             // The order being fulfilled
    new CriteriaResolver[](0), // Dont worry about this
    conduitKey,                // Key of the conduit address to interact with seaport
    recipientOfOfferItems      // Fulfiller decides who to send received items to 
);

Once the order is fulfilled, the items offered up by the lender will now be sitting inside the rental wallet of the owner that invoked the fulfillment. Meanwhile, the payment for the order will be held in an escrow contract until the rental is stopped and assets are returned to the lender.

The function signature for stopping a rental order is very simple, accepting a RentalOrder struct as its sole parameter:

function stopRent(rentalOrder memory order) external;

struct rentalOrder {
    bytes32 seaportOrderHash;
    item[] items;
    hook[] hooks;
    ordertype orderType;
    address lender;
    address renter;
    address rentalWallet;
    uint256 startTimestamp;
    uint256 endTimestamp;
}

One way that the protocol saves gas during rental creation is by writing data to storage as infrequently as possible. So, rather than store each parameter of the RentalOrder struct, only its hash is saved in protocol storage. For the rest of the parameters, they can be retrieved from the RentalOrderStarted event which is emitted on each successful rental order fulfillment.

/**
 * @dev Emitted when a new rental order is started. PAYEE orders are excluded from
 *      emitting this event.
 *
 * @param orderHash        Hash of the rental order struct.
 * @param emittedExtraData Data passed to the order to be emitted as an event.
 * @param seaportOrderHash Order hash of the seaport order struct.
 * @param items            Items in the rental order.
 * @param hooks            Hooks defined for the rental order.
 * @param orderType        Order type of the rental.
 * @param lender           Lender EOA of the assets in the order.
 * @param renter           Renter EOA of the assets in the order.
 * @param rentalWallet     Wallet contract which holds the rented assets.
 * @param startTimestamp   Timestamp which marks the start of the rental.
 * @param endTimestamp     Timestamp which marks the end of the rental.
*/
event RentalOrderStarted(
    bytes32 orderHash,
    bytes emittedExtraData,
    bytes32 seaportOrderHash,
    Item[] items,
    Hook[] hooks,
    OrderType orderType,
    address indexed lender,
    address indexed renter,
    address rentalWallet,
    uint256 startTimestamp,
    uint256 endTimestamp
);

Using this data, the RentalOrder can be properly reconstructed. Then, during the call to stopRent, the order will be hashed and compared against the hashed orders that exist in storage.

When a match is found, the protocol will return the assets back to their original owner, and award a payout from the escrow contract. Thus, completing the life cycle of a rental.

There you have it! The complete breakdown of how rental transactions are processed by Endgame in tandem with Seaport. By offloading the fulfillment logic to Seaport, the Endgame protocol is able to focus on just the logic related to rental construction and processing. If you want to dig deeper into Endgame, you can view the protocol contract repository here.

And, if you have any questions on rental fulfillments, feel free to reach out to myself at alec@021.gg.

In this post, I will go over an implementation for how to create one of these hooks. The hook I'll be walking through is a reward share hook, which can provide additional incentives on top of a standard rental order. A reward share hook allows a renter and a lender of an asset to accrue rewards in another token during an active rental. Via the terms of the rental, the lender is able to define the exact percentage of how the rewards will be split (e.g., 30% for the renter and 70% for the lender). After the rental has concluded, the accrued assets can then be claimed.

Let's take a look at the basic structure of a hook.

For the reward share hook, we need a contract that registers an active rental upon its creation, and then, unregisters the rental once it has been stopped. Using those start and stop timestamps, an accrued reward can later be claimed directly by the renter. To do this, we'll need to leverage the hook's onStart() and onStop() functions.

To start, let's look at the structure of the hook contract without getting too bogged down with function implementations just yet.

contract ERC20RewardHook is IHook {
    // This is the protocol contract which will call the hook on rental start 
    address public createPolicy;

    // This is the protocol contract which will call the hook on rental stop
    address public stopPolicy;

    // The rentable token that is compatible with this hook
    address public gameToken;

    // The token which will be distributed as a reward to renters
    IERC20 public rewardToken;

    // award 1 gwei of reward token per block
    uint256 public immutable rewardPerBlock = 1e9;

    // holds info about an asset
    mapping(bytes32 assetHash => RentInfo rentInfo) public rentInfo;

    // holds info about accrued rewards
    mapping(address rewardedAddress => uint256 rewards) public accruedRewards;

    constructor(
        address _createPolicy,
        address _stopPolicy,
        address _gameToken,
        address _rewardToken
    ) {
        createPolicy = _createPolicy;
        stopPolicy = _stopPolicy;
        gameToken = _gameToken;
        rewardToken = IERC20(_rewardToken);
    }

    modifier onlyCreatePolicy() {
        require(msg.sender == createPolicy, "not callable unless create policy");
        _;
    }

    modifier onlyStopPolicy() {
        require(msg.sender == stopPolicy, "not callable unless stop policy");
        _;
    }

    modifier onlySupportedTokens(address token) {
        require(token == gameToken, "token is not supported");
        _;
    }

    // ... Hook function implementations will go here
}

There are two important modifiers ( onlyCreatePolicy and onlyStopPolicy) which have been implemented to prevent the hook from being misused.

Because this hook will be tracking accrued rewards for active rentals and distributing tokens, it must prevent any address except the rental protocol from interacting with the hook, and it also must prevent a rental order which uses some random token from also being able to cash in on this hook.

There are also mappings for the rented assets and the rewards that have been accrued:

// holds info about an asset
mapping(bytes32 assetHash => RentInfo rentInfo) public rentInfo;

// holds info about accrued rewards
mapping(address rewardedAddress => uint256 rewards) public accruedRewards;

Their structs are defined as follows:

// Info stored about each rental
struct RentInfo {
    uint256 amount;
    uint256 lastRewardBlock;
}

// Info about the revenue share
struct RevenueShare {
    address lender;
    uint256 lenderShare;
}

The RevenueShare struct is important because this defines the terms for the revenue split. On rental creation, the lender crafts a RevenueShare struct defining what percentage of the rewards they want to receive from the hook. More on how this works in the next section.

Next, we'll handle the functionality for registering a new rental order with the hook contract. This function has a few responsibilities:

• enforce proper function access using modifiers

• calculate rewards (if any) that have already accrued for the renter

• update storage with the asset and timestamp of the new rental

Let's begin with the onStart definition along with its modifiers:

// hook handler for when a rental has started
function onStart(
    address safe,
    address token,
    uint256 identifier,
    uint256 amount,
    bytes memory data
) external onlyCreatePolicy onlySupportedTokens(token) {
    // Decode the revenue split data
    RevenueShare memory revenueShare = abi.decode(data, (RevenueShare));

    // ... Implementation continues on 
}

onStart modifiers make sure that only expected rentals and expected senders can interact with the hook. Next, the function accepts the rental safe address, the token, its identifier, the amount of tokens in the rental order, and any extra data that the hook may need. The data is passed in by the lender when they sign a new order to lend, which allows for implementation flexibility since not all uses for hooks can be known upfront. For our example, this is a RevenueShare struct which tells the hook how to split the rewards between the renter and lender.

Now, we'll move on to calculating previous rewards. Since a single renter can have multiple orders that interact with the hook, we must be certain that they accrue rewards for each of their rentals. So, each time a new rental is added, all accrued rewards from active rentals are calculated so they do not get overwritten by a new rental coming in.

// ... Previous code

// get the last block that the rewards were accrued
uint256 lastBlock = rentInfo[assetHash].lastRewardBlock;

// get the amount currently stored
uint256 currentAmount = rentInfo[assetHash].amount;

// if the last block that a reward was accrued exists and the amount is nonzero,
// calculate the latest reward. Otherwise, this is a first-time deposit so
// there are no rewards earned.
if (lastBlock > 0 && currentAmount > 0) {
    // The amount of blocks to reward
    uint256 blocksToReward = block.number - lastBlock;

    // since the last time reward were accrued, the reward is distributed per 
	// block per token stored. Divide by 1e18 to account for token decimals
    uint256 latestAccruedRewards = (blocksToReward * rewardPerBlock * 
		currentAmount) / 1e18;

    // determine the split of the rewards for the lender
    uint256 lenderAccruedRewards = (latestAccruedRewards * 
		revenueShare.lenderShare) / 100;

    // determine the split of the rewards for the renter
    uint256 renterAccruedRewards = latestAccruedRewards - lenderAccruedRewards;

    // Effect: accrue rewards to the lender
    accruedRewards[revenueShare.lender] += lenderAccruedRewards;

    // Effect: accrue rewards to the safe/renter
    accruedRewards[safe] += renterAccruedRewards;
}

// ... Implementation continues on

The last block used to calculate an accrual combined with the current block creates a time range. This range is then multiplied by the preconfigured reward per block which determines the total token reward for the range.

Then, those tokens are credited to the renter's and lender's accounts, which will be transferred once the tokens are claimed from the hook.

The function definition for onStop is very similar to what we have seen previously. The only difference is that the modifier now checks that the Stop Policy is the one that calls the hook.

// handler for when a rental has stopped
function onStop(
    address safe,
    address token,
    uint256 identifier,
    uint256 amount,
    bytes memory data
) external onlyStopPolicy onlySupportedTokens(token) {
    // ...Implementation will go here
}

For the body of the function, the hook will again behave very similar to onStop. Rewards will be accrued in storage, and the total number of rented assets for the renter will be decremented by the amount field.

// ... Previous code

// get the last block that the rewards were accrued
uint256 lastBlock = rentInfo[assetHash].lastRewardBlock;

// get the amount currently stored
uint256 currentAmount = rentInfo[assetHash].amount;

// The amount of blocks to reward
uint256 blocksToReward = block.number - lastBlock;

// since the last time reward were accrued, the reward is distributed per block per token stored.
// Divide by 1e18 to account for token decimals
uint256 latestAccruedRewards = (blocksToReward * rewardPerBlock * currentAmount) / 1e18;

// determine the split of the rewards for the lender
uint256 lenderAccruedRewards = (latestAccruedRewards * revenueShare.lenderShare) / 100;

// determine the split of the rewards for the renter
uint256 renterAccruedRewards = latestAccruedRewards - lenderAccruedRewards;

// Effect: accrue rewards to the lender and renter
accruedRewards[revenueShare.lender] += lenderAccruedRewards;
accruedRewards[safe] += renterAccruedRewards;

// Effect: update the amount of tokens currently rented and the latest block that rewards accrued
rentInfo[assetHash].amount -= amount;
rentInfo[assetHash].lastRewardBlock = block.number;

// ... Implementation continues on

Once a rental has ended, this hook contract supports claiming the reward tokens directly from the rental hook. Either the lender, renter EOA, or the rental wallet can claim their share of the tokens.

function claimRewards(address rewardedAddress) external {
    // check if the caller is the lender or is a rental safe
    bool isClaimer = msg.sender == rewardedAddress;

    // make sure the caller is the claimer, or they are the owner
    // of the safe
    require(
        isClaimer || ISafe(rewardedAddress).isOwner(msg.sender),
        "not allowed to access rewards for this safe"
    );

    // store the amount to withdraw
    uint256 withdrawAmount = accruedRewards[rewardedAddress];

    // Effect: update the accrued rewards
    accruedRewards[rewardedAddress] = 0;

    // Interaction: Transfer the accrued rewards
    rewardToken.transfer(msg.sender, withdrawAmount);
}

To kick off the test, we'll start with the setup function. The contracts will be deployed, the hook will be registered with the protocol, and tokens will be minted to the hook contract so that it can payout rewards.

// ... Previous code

// deploy contracts needed for hook
rewardToken = new MockERC20();
hook = new ERC20RewardHook(
    address(create),
    address(stop),
    address(gameToken),
    address(rewardToken)
);

// admin enables the hook. Use binary 00000110 so that the hook
// is enabled for `onStart` and `onStop` calls
vm.prank(deployer.addr);
guard.updateHookStatus(address(hook), uint8(6));

// fund the hook contract with some reward tokens
rewardToken.mint(address(hook), 100e18);

// ... Implementation continues on

Next, we can kick off a test that will perform a rental that will execute the onStart function of the hook contract. Then, we'll roll forward in time and stop the rental so that the onStop function is called.

Finally, the rewards can be claimed by both the lender and the renter.

function test_Success_RewardShare() public {
    // start the rental. This should activate the hook and begin
    // accruing rewards while the rental is active.
    RentalOrder memory rentalOrder = _startRentalWithGameToken();

    // roll ahead by 100 blocks so that rewards can accrue
    vm.roll(block.number + 100);

    // speed up in time past the rental expiration
    vm.warp(block.timestamp + 750);

    // stop the rental
    vm.prank(alice.addr);
    stop.stopRent(rentalOrder);

    // owner of the safe can claim tokens
    vm.prank(bob.addr);
    hook.claimRewards(address(bob.safe));

    // lender of the rental can claim tokens
    vm.prank(alice.addr);
    hook.claimRewards(alice.addr);

    // earned rewards should be 100 blocks * 1 gwei reward per block * 1e18 token, 
	// which is 100 gwei
    assertEq(rewardToken.balanceOf(bob.addr), 30000000000); // 30 gwei
    assertEq(rewardToken.balanceOf(alice.addr), 70000000000); // 70 gwei
}

Hopefully this concrete example of a hook implementation is enough to show how powerful the hook architecture can be when it comes to extending rental functionality.

This tutorial left out portions of code in the implementation that weren't relevant for discussion. To view the full source, you can take a look at the contract implementation and the test file.

If you have any questions on how hooks work, feel free to reach out to myself at alec@021.gg. And, if you want to integrate hooks into your own ERC721 or ERC1155 project, you can contact naz@021.gg for more details.

One of the most powerful features of Endgame is its ability to extend rental functionality through the use of hooks. These are custom contracts attached to an order by a lender. Once the order is fulfilled, these hooks can operate at the start of a rental, at the end of a rental, or alongside transactions that originate from rental wallets, allowing customized rental flows on a per-collection basis.

To understand how hooks fit into the protocol, we'll first look at the IHook interface, which must be implemented to construct a valid hook contract.

The fully commented source code can be found here.

interface IHook {
    // Triggers this hook call during a transaction involving a rented asset with
    // an active hook address attached to its metadata.
    function onTransaction(
        address safe,
        address to,
        uint256 value,
        bytes memory data
    ) external;

    // Triggers this hook call when a rental has been started.
    function onStart(
        address safe,
        address token,
        uint256 identifier,
        uint256 amount,
        bytes memory extraData
    ) external;

    // Triggers this hook call when a rental has been stopped.
    function onStop(
        address safe,
        address token,
        uint256 identifier,
        uint256 amount,
        bytes memory extraData
    ) external;
}  

At different points in the lifecycle of a rental, the hook contract can be invoked by the protocol, so not all functions in this interface have to be implemented to get the desired behavior.

After an asset has been rented, the owner of the rental safe is now allowed to begin making transactions that originate from the rental wallet. If the hook in the order implements the onTransaction function, it will first be associated with a target contract. This can be any contract that the rental safe may interact with while renting the asset. If a transaction specifies this target contract in its to field of a transaction, then the hook contract will be called first to act as a middleware between the rental safe and the target contract.

A good example for wanting to use this hook is for an asset that might have a single-use function that can only be called once, which would want to be reserved for the original owner of the asset to call, and not the renter.

During the fulfillment process of a rental, the onStart hook can be invoked to perform any actions at the very start of the rental. At the time that the onStart hook is invoked, the asset will have just been sent to the rental wallet.

During the process of stopping a rental, the onStop hook can be invoked to perform any actions at the very end of the rental. At the time that the onStop hook is invoked, the asset will have already been removed from the rental wallet.

Hooks are not permission-less. Since hook contracts are middleware by nature, it is important that the use of them be limited to a well-vetted, whitelisted selection to prevent protocol exploits. Any hooks deemed fit for use can be added via the protocol's hook updating functions:

/**
 * @notice Connects a target contract to a hook.
 *
 * @param to   The destination contract of a call.
 * @param hook The hook middleware contract to sit between the call
 *             and the destination.
 */
function updateHookPath(address to, address hook) external; 

/**
 * @notice Toggle the status of a hook contract, which defines the functionality
 *         that the hook supports.
 *
 * @param hook The hook contract address.
 * @param bitmap Bitmap of the status.
 */
function updateHookStatus(address hook, uint8 bitmap) external; 

For a hook to be added to the protocol, both of these functions must be invoked by an admin:

• UpdateHookPath: This is used to point a hook contract at an intended target address. This will ensure that this hook contract can only be invoked when a rental wallet creates a transaction with a specific to address.

• UpdateHookStatus: This function determines at which point in the lifecycle of the rental that the hook will activate. It can be set to be invoked in any combination of: on rental start, on rental end, and during rental transactions.

When updating a hook's status, the protocol uses a bitmap to track the exact configuration of the hook. This allows specifying any combination of hook functions as a single uint8. Our current implementation is as follows:

• 00000001 or 1: enables hook activation during a transaction with an active rental

• 00000010 or 2: enables hook activation on rental start

• 00000100 or 4: enables hook activation on renal stop

For example, updating a hook status for both onStart and onTransaction might look like this:

// Use binary 00000011 so that the hook is enabled for onStart 
// and onTransaction calls only
guard.updateHookStatus(address(hook), uint8(3));

With a hook contract deployed and activated on the protocol, a lender will be able to specify assets to lend alongside any hooks to apply to those assets. This gives the lender full control over how their assets will be used throughout the lifecycle of the rental.

Adding a hook to a rental order requires passing in an array of hooks to the order before signing it. An example hook might look something like this:

// Define the hook for the rental
Hook[] memory hooks = new Hook[](1);
hooks[0] = Hook({
    // the hook contract to target
    target: address(hook),
    // index of the item in the order to apply the hook to
    itemIndex: 0,
    // any extra data that the hook will need.
    extraData: ""
});

Lets break down each of these fields:

• Target: The address of the hook contract being invoked. Control flow will pass to this contract during the rental process to execute additional functionality.

• ItemIndex: Since we use seaport to power our token swaps, the asset for which you want the hook to be activated will be the item index of the seaport OfferItem array in the order.

• ExtraData: This is any extra data that the hook contract may want when it is invoked. This allows for maximum flexibility when designing hooks since we cannot predict all possible use-cases.

The hooks will then be passed into an OrderMetadata struct. Each rental order will contain a single metadata struct that defines the terms for the rental. It is crucial that both the lender and the renter have agreed upon the same terms. To guarantee this, the OrderMetadata struct is hashed and then placed in the zoneHash field of a seaport OrderComponents struct:

// Endgame order metadata for a rental order
struct OrderMetadata {
	// Type of order being created.
	OrderType orderType;
	// Duration of the rental in seconds.
	uint256 rentDuration;
	// Hooks that will act as middleware for the items in the order.
	Hook[] hooks;
	// Any extra data to be emitted upon order fulfillment.
	bytes emittedExtraData;
}

// Seaport order components
struct OrderComponents {
    address offerer;
    address zone;
    OfferItem[] offer;
    ConsiderationItem[] consideration;
    OrderType orderType;
    uint256 startTime;
    uint256 endTime;
    bytes32 zoneHash; // <-- the one we care about
    uint256 salt;
    bytes32 conduitKey;
    uint256 counter;
}

From here, the rental order is executed with seaport. To ensure that the fulfiller has agreed to the same order metadata as the lender, they will need to include the exact same OrderMetadata struct into their order as extraData. But for this post, I wont go into how exactly a rental order is constructed. Once the order has been fulfilled, the hooks will reach Endgame's contract and will be extracted and decoded. More on this in the next section.

Lets look at how a hook will behave in each of the three different ways that it can be invoked during the process of a rental order.

A hook starts its journey once it is decoded by a seaport zone contract after an order has been fulfilled. A zone contract allows you to extend the behavior of a traditional seaport order fulfillment. In our case, we perform the order fulfillment and introduce extra bookkeeping to create rentals instead of permanent trades.

During rental creation, a call to _addHooks is made in the Create policy contract that, in turn, will reach out to the hook contract to execute. It passes the rental wallet address, token, token ID, amount, and any extra data provided. There is no limit to how many hooks can be executed on a single order, so each one will be looped through and called during the rental creation process.

// Check that the hook is reNFT-approved to execute on rental start. This checks to see 
// if the 0x00000010 bit is active on the hooks's status bitmap in storage
if (STORE.hookOnStart(target)) {

    // ... Do some stuff

    // Call the hook with data about the rented item.
    IHook(target).onStart(
         rentalWallet,
         offer.token,
         offer.identifier,
         offer.amount,
         hooks[i].extraData
    );

    // ... Do some stuff
}

From here, the contract will execute normally and allow for any extension of functionality that the implementor has introduced.

The process of executing a hook at the end of the rental is very similar to how it behaves at the start of the rental. During a rental stop, all data that was used to create the rental order must also be given to the Stop policy contract to end the order. This includes the original hook entries that were present on the order.

A call to _removeHooks is made in the Stop policy contract that, in turn, will reach out to the same hook contracts which were passed in during the start of the order. They will also receive the same parameters from before.

// Check that the hook is reNFT-approved to execute on rental stop. This checks to see 
// if the 0x00000100 bit is active on the hooks's status bitmap in storage
if (STORE.hookOnStop(target)) {

    // ... Do some stuff

    // Call the hook with data about the rented item.
    IHook(target).onStop(
        rentalWallet,
        item.token,
        item.identifier,
        item.amount,
        hooks[i].extraData
    )

    // ... Do some stuff
}

After this, the stopping of the rental will wrap up as usual.

Hooks can additionally be invoked throughout the duration of the rental, depending on what kinds of transactions the renter makes from their rental wallet. By default, the rental wallet disables any transactions originating from it that involve transferring or burning a rented asset.

For everything else, it leaves it up to the hooks associated with the target address in the transaction to handle whether it should either reject the transaction or, in other cases, provide additional functionality by acting as middleware.

Endgame uses Safe wallets as the default rental wallet for the protocol. Any transaction coming from the rental wallet requires a signed transaction from the owner which is then passed through a custom Guard contract.

Within the guard, there is logic that determines if the target for the transaction has a hook contract associated with it. This association is set by an admin like this:

// admin enables the hook path to point to the game contract
guard.updateHookPath(address(game), address(hook));

By doing this, any time the guard contract detects a transaction to address(game), it will check storage for the hook contract associated with that address. Once it has the hook, it then needs to check if the hook has been activated for onTransaction hooks:

// Checks if the 0x00000001 bit is active on the hooks's status bitmap in storage
bool hookIsActive = STORE.hookOnTransaction(hook);

If the address being called in the transaction both has an associated hook contract and the hook contract is enabled for onTransaction, then control flow will be passed to the hook contract with _forwardToHook found here.

function _forwardToHook(
    address hook,
    address safe,
    address to,
    uint256 value,
    bytes memory data
) private {

    // Call the onTransaction hook function.
    IHook(hook).onTransaction(safe, to, value, data); 

    // ... Do some stuff
}

With this construction, the hook will get the final say on whether the transaction should be prevented. This is a great use-case for hooks that wish to prevent custom function selectors on a contract from being executed by a renter. For example, you could imagine some type of ERC721 with a function that allows combining two assets together to make a third and destroying the original two in the process.

A hook contract would allow the original owner of the asset to prevent the rented ERC721 from being able to participate in this function by defining a custom rule that will revert if any asset tries to use the function selector associated with that functionality.

The possibilities for how hooks can be used truly have no limit. They were designed with flexibility in mind so that each project using a hook could define the use-case that works best for them. For some examples of implemented hooks, you can find them all here.

If you have any questions on how hooks work, feel free to reach out to myself at alec@021.gg. And, if you want to integrate hooks into your own ERC721 or ERC1155 project, you can contact naz@021.gg for more details.

We use Remix as our front end framework. As it’s powered by React it offers us lots of goodies available in the React ecosystem. Things like Tanstack Query for handling any (asynchronous) state with GraphQL Request, Wagmi and Viem for handling any onchain/wallet interactions, Radix Primitives and TailwindCSS for anything UI related.

For testing our application we leverage Storybook’s Test Runner as a component testing framework and Playwright for the heavier end-to-end testing. Both are fantastic tools to keep core functionality in check.

Everything is written in TypeScript. Most of these choices were locked-in from the onset.

Now, if there’s any guiding principle in our development team, it would be: “be pragmatic”. This captures a slew of software development principles into one overarching creed. Think: YAGNI, KISS, “premature optimization is the root of all evil”, principle of least power, and probably some others. The thing with code, when you’ve worked with it long enough, is that at some point you discover the code itself has a voice. Code can’t be simply reduced to expressions, variables and operations cast from the void of the programmer’s mind. This stance will deafen you to this voice. Code whispers when you find yourself repeating things. Code speaks when you struggle to find elegance. Code shouts when you’re trying to bend an implementation to its breaking point. Pragmatism appoints code itself a powerful advisor.

Our back end exposes a GraphQL API to fetch and mutate data. As such we had a rich amount of choices for handling back end interfacing but opted for simplicity first. We leverage GraphQL Request in tandem with Tanstack Query.

Tanstack Query especially exposes a delightful API to handle a wide variety of data fetching (while not being limited to only data fetching) scenarios. Things like TTL, invalidation, “infinite” (e.g. paginated) queries, loading and error states, mutations, etc. are all made available in a relatively light-weight package. GraphQL Request, in tandem with GraphQL Codegen, allows us to easily and flexibly define the data we need for certain views. We try to colocate GraphQL queries where it's sensible and leverage fragments to reduce duplication. GraphQL Codegen provides tooling like FragmentType and useFragment() to handle actual types and properties returned by queries—as opposed to using GraphQL schema types as props directly. For more info, read up on "fragment masking".

One fantastic benefit of using Tanstack Query is that it allows you to introduce another layer of separation between the UI and framework (like Remix). Essentially, it theoretically allows us to eject from a server framework completely and still have fully functioning views. The server side prefetching is just extra. This approach proved immensely useful later.

A few months after Wagmi was released we integrated it into our v2 front end to simplify a lot of logic concerning wallet sessions. Similarly, to simplify internals and interaction between our v2 front end and protocol, we added support for Viem in our v2 SDK. These libraries, in our opinion, are an absolute joy to work with and provide simple yet powerful foundations of interacting with chains and wallets. This experience made it an obvious choice for Endgame as well.

We leverage WalletConnect’s Web3 Modal for wallet connections. While Wagmi does provide the option to handle the injected connector alongside, we figured presenting a unified, familiar interface regardless of connector was easiest to maintain while providing a consistent UX.

For Endgame protocol interfacing we wrote a small library wrapping parts of our back end interface, Wagmi, and—since our protocol leverages Seaport—SeaportJS with Tanstack Query. The library exposes a set of React hooks which provide us data about chain configuration, permissions, rental status, and relevant rental and safe account actions. In honesty, SeaportJS we might eject from at some later point, as it provides a lot of tooling to interface with the Seaport protocol, whereas we just use a small subset. For velocity's sake though, having SeaportJS check and ask for approvals before initiating a rental transaction is pretty nice to have.

We found Wagmi’s MockConnector one of its biggest boons. It allows us to, well, mock a connected wallet. We have written a small harness around the MockConnector, allowing us to easily connect a test wallet for our end-to-end tests, or to mimic/impersonate any wallet for manual testing and debugging purposes. In the future we might write a more in-depth article on our approach here.

The danger with picking a full-fledged, off-the-shelf component library is that, at some point, you will need to fight the framework or accept some nauseating compromise. Most of these libraries (e.g. Material UI, Ant Design, Bootstrap, Chakra) design their components and interfaces, understandably, for the most broad cases. Many of these libraries also ship their own way of extending or overwriting their themes. Some have strong opinions on which custom styling solution works best. Some even provide their own styling solutions. The key thing is, with any UI library, you often find yourself writing your own wrappers anyway.

A “headless UI” library like Radix Primitives enables a very flexible approach to reusable components. It provides accessible primitives with a lot of hooks (not the React ones) to handle custom behavior. Additionally, a headless UI library is agnostic as to the preferred styling solution. You can use plain ol' CSS, Styled Components, Emotion, stylex—pick your poison, amirite? We choose Tailwind.

I’ll be honest. I love CSS. When you grok the cascade it allows for a very powerful and extensible paradigm to style user interfaces with. Recent advancements in the CSS specifications (and browsers actually implementing these) can make CSS a very fun logic playground. I love shipping things more though.

TailwindCSS allows us to mark up and style components fast, while retaining the ability to use plain ol’ CSS when the use-case calls for it. A specific example here would be styling third-party components. Sure, you can leverage Tailwind’s selector engine to apply styles to any child element, but seeing as regular Tailwind is hardly a feast for the eyes, overloading a className to style elements of a third party component will positively make your eyes bleed. Eject to a CSS file.

Remember how we said it’s important to listen to code?

We actually started developing Endgame on top of Next.js. We use this framework for our v2 application and thereby accrued quite some experience with it. We knew Next.js has its faults and foot guns but an experienced programmer would agree reusing a stack you have experience in, for a comparable project, is a very sensible choice.

The tech landscape—especially the front end ecosystem—is ever shifting however, and while developing Endgame we found ourselves in the midst of Next.js releasing v13 (and later v14). The v13 release added the powerful App Router, leveraging React Server Components (RSC). Initial adoption took some getting used to and we had to restructure a few modules but things chugged along fine. Over the months we would grow increasingly disenchanted by Next.js’ offering however. Partly because RSC exposed, in our opinion, a very misguided approach: that it makes sense to shoehorn a client side UI library into—checks notes—a server-side templating language. Partly because we kept discovering Next.js has very strong opinions on how to handle some web platform core APIs. We had to write a quite some indirections to deal with these (looking at you, useSearchParams()).

The code started shouting.

At this point, about 6 months in, we made the decision to migrate framework. We had been eying Remix for some time because of its sensible approach to expose Web APIs rather than abstract them. Moreover, much of our logic was required on the client anyway so the reduced bundle payloads were hardly worth the effort. The key thing to migrate over was routing. The rest pretty much worked out of the box because of our decoupled architecture. The core engine swap essentially took about 2-3 days. Rewriting some of the indirections took about the same time. Bells and whistles, another two days or so. The result, however, was code tranquility and a big boost to our velocity.

Remix offered us vastly more transparency and control over its layers.

We’re very excited to have launched Endgame and we’re grateful we can start to share our journey with everyone. It has taught us a lot. We hope to have given you an interesting cursory look at how we architected our front end. Now, each component in our architecture could merit its own article but we wanted to provide a comprehensive overview first. Stay tuned for some more in-depth content!

Note: This is co-published on rombrom.com.