Add support for multiple namespaces in one config

[dk1a]

I talk about tables because I think what works for them will work for systems, tables are more prevalent in the config, and systems have no sync to worry about. But u can see them both in the examples.
The examples are slightly contrived to show what happens when key and name differ

Current state

mudConfig tables have

• Record key which represents the library name. It's used for most client stuff
• namespace and name, which are used for on-chain tableId
• tableId which is composed of namespace+name. It's used for all on-chain stuff

namespace is currently global (but #971 aims to change it)

Record key and name are sometimes used interchangeably (like in store-cache), but they can currently be different, which can lead to problems.

export default mudConfig({
  namespace: "",
  tables: {
    CounterTableN: {
      schema: "uint32",
    },
    // Until namespace overrides, CounterTableNamespaced must be manually deployed in PostDeploy
  },
  systems: {
    IncrementSystem: {
      name: "Increment",
      openAccess: true,
    },
  },
  excludeSystems: [
    // Until namespace overrides, this system must be manually deployed in PostDeploy
    "IncrementNamespacedSystem",
  ],
});

Solution 1

Keep table key and name separate and make the separation stronger

1. Explicitly name table key as tableKey, and table name as name
2. Never use them interchangeably, because they can differ
3. Most client things would use tableKey, but some (like subscriptions) would still have name around, since sync works with the whole world and not just what's in the config
4. Per-table namespace overrides just work (since namespace+name has to be unique, not namespace+tableKey, you won't get ambiguity even with an existing world)
5. All on-chain things use name as before

export default mudConfig({
  namespace: "",
  tables: {
    CounterTableN: "uint32",
    CounterTableNamespaced: {
      // name can't actually be specified for tables, but it will be effectively different from tableKey because <=16 length limit
      // name: "CounterTableN"
      namespace: "namespace",
      schema: "uint32",
    }
  },
  systems: {
    IncrementSystem: {
      name: "Increment",
      openAccess: true,
    },
    IncrementNamespacedSystem: {
      namespace: "namespace",
      name: "Increment",
      openAccess: true,
    }
  },
});

Solution 2

Unify table key and name

1. Remove name from table config
2. name and tableKey can not differ, so have zod check that tableKey.length <= 16
3. Everything uses name, which is also tableKey
4. Per-table namespace overrides must be made to work , see 2.1 and 2.2
5. All on-chain things use name as before

Sub-solution 2.1

Keep only 1 root namespace

1. No per-table namespace overrides, you must make a separate config for a separate namespace
2. We have to allow multiple mud.config in one package (this is a separate issue, which would particularly affect cli and client)

// first config (there're 2)
export default mudConfig({
  namespace: "",
  tables: {
    CounterTableN: "uint32",
  },
  systems: {
    Increment: {
      openAccess: true,
    },
  },
});

// second config (there're 2)
export default mudConfig({
  namespace: "namespace",
  tables: {
    CounterTableN: "uint32",
  },
  systems: {
    Increment: {
      openAccess: true,
    }
  },
});

Sub-solution 2.2

Make tables config option grouped by namespace

1. Rather than per-table namespace, we get per-namespace table
2. This does not depend on having multiple mud.config in one package

export default mudConfig({
  tables: {
    "": {
      CounterTableN: "uint32",
    },
    "namespace": {
      CounterTableN: "uint32",
    }
  },
  systems: {
    "": {
      Increment: {
        openAccess: true,
      },
    },
    "namespace": {
      Increment: {
        openAccess: true,
      },
    },
  },
});

[dk1a]

1 seems like the simplest option that mostly preserves the status quo
2.1 strongly depends on a separate issue that's probably bigger than this one, so hard to say
2.2 I kinda like this, but for both 2.1 and 2.2 being restricted to short file names feels bad

I currently prefer 1 but may have missed something and curious about your opinions

[alvrs]

One thought i'd like to throw in the pot: eventually we should have something that allows devs to "download" a mud config of an existing world (ie mud config --worldAddress 0x1234 -> generates a mud.config.ts with all the tables and systems of that world). This would improve the dev ex for extending existing worlds, because now our client libs can have strong types based on the config of the existing world.

With this in mind we'll have to find a way to support non-unique names for tables and systems. With option 1 we'd have to somehow generate a unique name for the table key, probably something like concatenating namespace and name. What I don't like about this approach is that it's harder to explain what the difference between key and name is, and what each are used for.

My personal favorite is approach 2.2, or slight variation (let's call it 2.3, see below), because it maps the concept of namespaces and names well to the datastructure being used (namespaces have to be unique, names have to be unique within a namespace).

Approach 2.3:

export default mudConfig({
  namespaces: {
    "": {
      tables: {
        CounterTableN: "uint32",
      },
      systems: {
        Increment: {
          openAccess: true
        }
      }
    },
    "namespace": {
      tables: {
        CounterTableN: "uint32"
      },
      systems: {
        Increment: {
          openAccess: true
        }
      }
    }
  }
});

Potentially we could also allow a top level "tables" / "systems" key for the root namespace, and only nest in the namespaces key for non-root namespaces, but not sure about that yet.

One nice side effect of approach 2.3 is it's possible to use the table schema shortcuts also for namespaced tables.

[holic]

Very into the idea of 2.3, with:

• explicit parity of table key + table name (including 16 char enforcement of both name + namespace)
• namespace-grouped tables/systems (helps with code organization/visualization)
• would love to see a "shortcut" of top-level tables/systems that assume namespace ""
  • or, if not, maybe we give a name to the root namespace?
  • maybe you can only use the "shortcut" if you only have root-level tables/systems (OR)

[dk1a]

Good points, especially about the downloading - didn't think of that.
btw fun fact about 2.2 is I started writing it like 2.3, but then changed midway because of my status quo bias here.
I agree with 2.3, and since we seem to have consensus already I can make a PR some time soon, wanna deal with a few other things 1st though

[alvrs]

Update: new config has type support for multiple namespaces, but not enabled yet because of codegen limitations (tables can have the same name in different namespaces, which would lead to file name conflicts). Codegen support is being added in #2840

[holic]

done in #2968